4 ms·

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 en

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.

jnbiche 10y ago
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.
- iamjeff 10y ago
  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 https://twitter.com/josephpaulcohen joseph@josephpcohen.com http://josephpcohen.com/w/ http://josephpcohen.com/w/ https://www.linkedin.com/in/josephpcohen https://www.linkedin.com/in/josephpcohen https://github.com/ieee8023 https://github.com/ieee8023 https://www.reddit.com/user/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://www.linkedin.com/in/henry-z-lo-6a11461b https://github.com/henryzlo https://github.com/henryzlo [3] http://academictorrents.com/about.php 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&coll=DL&CFID=661488745&CFTOKEN=24433760 http://dl.acm.org.sci-hub.cc/citation.cfm?id=2616528&dl=ACM&...) - Academic Torrents - Simple Pitch (https://docs.google.com/presentation/d/1JC2d1g9U6HaenGSn_Xvkl7FXyNo5LgVpLFQqCrNgF6k/edit#slide=id.p https://docs.google.com/presentation/d/1JC2d1g9U6HaenGSn_Xvk...) - Academic Torrents: Scalable Data Distribution (http://arxiv.org/pdf/1603.04395v1.pdf 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_every_publicly_available_reddit_comment/ https://www.reddit.com/r/datasets/comments/3bxlg7/i_have_eve...)
  - iamjeff 10y ago
    Looks like I spoke too soon. Here is one of the founders on HN as well: https://news.ycombinator.com/user?id=ieee8023 https://news.ycombinator.com/user?id=ieee8023.
microcolonel 10y ago
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.
- dsl 10y ago
  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.
  - WhitneyLand 10y ago
    graceful degradation is a good thing. beautiful path can still be used by a lot of people.
  - jnbiche 10y ago
    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.
NeutronBoy 10y ago
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?
- WhitneyLand 10y ago
  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-position-of-duplicate-http-get-query-keys 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-restful-api#autoloading 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.
- Senji 10y ago
  GET /apiv2/entries?cat=datasets+papers

jnbiche 10y ago

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.

iamjeff 10y ago
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 https://twitter.com/josephpaulcohen joseph@josephpcohen.com http://josephpcohen.com/w/ http://josephpcohen.com/w/ https://www.linkedin.com/in/josephpcohen https://www.linkedin.com/in/josephpcohen https://github.com/ieee8023 https://github.com/ieee8023 https://www.reddit.com/user/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://www.linkedin.com/in/henry-z-lo-6a11461b https://github.com/henryzlo https://github.com/henryzlo [3] http://academictorrents.com/about.php 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&coll=DL&CFID=661488745&CFTOKEN=24433760 http://dl.acm.org.sci-hub.cc/citation.cfm?id=2616528&dl=ACM&...) - Academic Torrents - Simple Pitch (https://docs.google.com/presentation/d/1JC2d1g9U6HaenGSn_Xvkl7FXyNo5LgVpLFQqCrNgF6k/edit#slide=id.p https://docs.google.com/presentation/d/1JC2d1g9U6HaenGSn_Xvk...) - Academic Torrents: Scalable Data Distribution (http://arxiv.org/pdf/1603.04395v1.pdf 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_every_publicly_available_reddit_comment/ https://www.reddit.com/r/datasets/comments/3bxlg7/i_have_eve...)
- iamjeff 10y ago
  Looks like I spoke too soon. Here is one of the founders on HN as well: https://news.ycombinator.com/user?id=ieee8023 https://news.ycombinator.com/user?id=ieee8023.

microcolonel 10y ago

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.

dsl 10y ago
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.
- WhitneyLand 10y ago
  graceful degradation is a good thing. beautiful path can still be used by a lot of people.
- jnbiche 10y ago
  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.

NeutronBoy 10y ago

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?

WhitneyLand 10y ago
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-position-of-duplicate-http-get-query-keys 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-restful-api#autoloading 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.
Senji 10y ago
GET /apiv2/entries?cat=datasets+papers