Hacker News Reader

Hacker News

Comment by WhitneyLand | Hacker News Reader

Parent Full thread

WhitneyLand

API suggestions:

1). Don't use hard coded values for types

>GET /apiv2/entries?cat=6 -- List entries that are datasets

>GET /apiv2/entries?cat=5 -- List entries that are papers

These could be written as: /apiv2/entries/datasets /apiv2/entries/papers

2). You may not need path elements like entries, entry, collection, and collection name. For example further simplification would leave

  /datasets

  /papers

3). Don't use capitals like this, switch to lowercase: /apiv2/entry/INFOHASH

4). Use HTTP verbs in a standard, semantic way. For example this

  POST /apiv2/collection -- create an collection

  POST /apiv2/collection/collection-name/update

  POST /apiv2/collection/collection-name/delete

  POST /apiv2/collection/collection-name/add

  POST /apiv2/collection/collection-name/remove

This could all be collapsed into one form and would in turn be more familiar to developers.

View on HN

I strongly agree with these suggestions, if the creator(s) happen to read this.

And while these suggestions may seem like nitpicking, they are not.

While not everything around REST APIs is entirely standard, there's a great deal of agreement about proper resource naming and use of HTTP verbs. If you follow these widely-used standards, not only will developers find it much easier to interact with your API, but also there is a lot of tooling and client libraries out there built specifically to work with APIs that use HTTP verbs and URIs in the standardized ways.

Hi. I found this site late last night while looking for material for a hobby project. Really, really awesome site.

I also found the creators here [1] and here [2]...maybe you can help shoot them an e-mail so that they can acknowledge a lot of the praise on this thread and the flood of helpful suggestions. Additional contributors can also be found here [3] as well as related publications/presentations [4] including a massively interesting Reddit discussion [5].

[1]- Joseph Paul Cohen https://twitter.com/josephpaulcohen joseph@josephpcohen.com http://josephpcohen.com/w/ https://www.linkedin.com/in/josephpcohen https://github.com/ieee8023 https://www.reddit.com/user/ieee8023

[2]- Henry Z Lo henryzlo@cs.umb.edu https://www.linkedin.com/in/henry-z-lo-6a11461b https://github.com/henryzlo

[3] http://academictorrents.com/about.php

[4]- Academic Torrents: A Community-Maintained Distributed Repository (http://dl.acm.org.sci-hub.cc/citation.cfm?id=2616528&dl=ACM&...) - Academic Torrents - Simple Pitch (https://docs.google.com/presentation/d/1JC2d1g9U6HaenGSn_Xvk...) - Academic Torrents: Scalable Data Distribution (http://arxiv.org/pdf/1603.04395v1.pdf)

[5]- I have every publicly available Reddit comment for research. ~ 1.7 billion comments @ 250 GB compressed. Any interest in this? (https://www.reddit.com/r/datasets/comments/3bxlg7/i_have_eve...)

Looks like I spoke too soon. Here is one of the founders on HN as well: https://news.ycombinator.com/user?id=ieee8023.

Question about your first point - doesn't it depend on the use case?

What would happen if I wanted to get a list of datasets and papers? (maybe in this case it's nonsensical, but it's a problem with some other APIs I've used and I've never figured a good way to work around it)

GET /apiv2/entries?cat=5&cat=6 vs 2 separate requests and client logic to combine results?

1) Does all this depend on use case? Yes, heavily. Best practices are needed, but final design choices are tailored.

2) I don't like dup query params, it's not well defined: http://stackoverflow.com/questions/1746507/authoritative-pos...

For returning multiple types at once there are a few common strategies.

For related types some APIs offer an "include" or "embed" approach like this: http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...

Another approach is to support a query syntax for items, where items is a container record for multiple possible types.

If a certain multi-type scenario super common you may want build the concept into the API itself as basic functionality.

Again, your final choice should be as simple as possible but no simpler, taking into account ease of use, performance, etc.

GET /apiv2/entries?cat=datasets+papers

I wouldn't get too dogmatic about REST. I've been working with it for years, and it seems that every time somebody makes a semantic HTTP API, they run into a URI length limit at some point.

Every semantic API ends up with an overriding parameter like _action=PUT because well intentioned API developers don't know that broken middleboxes exist on the internet until their beautiful creation collides with reality.

Most REST API frameworks that I'm aware of (e.g., Django REST framework) easily allow you to accept either the semantic HTTP actions, or an action parameter in the query string. Some also let you fall back to the `X-HTTP-Method-Override` header. I think these are even on by default in many frameworks. So fallback is pretty easy if you're using one of those, and even if you're not, it's still just an extra line or two in your routing, plus a little extra error handling in your client for error code 405.

I do agree that you should have a fallback, but for reference, I've been consuming semantically-defined REST APIs for 4-5 years now, and I've never run into this problem. I agree with you that it can happen because of firewalls, etc, but it must be incredibly rare. Maybe in some corporate environments, for the usual BS reasons.

Also, if you use SSL/TLS, you won't run into this problem unless you're being MITM'd, like in some corporate environments (because no one in between server and client can tell what HTTP method is used). Use of SSL/TLS is probably why I haven't run into this in recent years.

graceful degradation is a good thing. beautiful path can still be used by a lot of people.

Reply on news.ycombinator.com