Best Practices for Designing a Pragmatic RESTful API
vinaysahni.com
Best Practices for Designing a Pragmatic RESTful API
1–10 of 38 posts
Re: Best Practices for Designing a Pragmatic RESTful API
#2If you're interested in API design the upcoming RFC standard might be of interest: https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis-06
Re: Best Practices for Designing a Pragmatic RESTful API
#3If you're interested in API design the upcoming RFC standard might be of interest: https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis-06
It’s great that a standard will eventually be set on API. So many different ways of using them so far.
Re: Best Practices for Designing a Pragmatic RESTful API
#4> Should the media type change based on Accept headers or based on the URL? To ensure browser explorability, it should be in the URL. The most sensible option here would be to append a .json or .xml extension to the endpoint URL.
I disagree with this. The most elegant solution is to use Accept headers, and you should therefore implement that. Of course, since those are hard to use from a browser, you should also solve that problem, but solve that problem separately. I usually do that by supporting an extra ?type=application/json query parameter, which internally the server-side code converts to an Accept header, which is then interpreted normally. Note that I use the media type, not a possibly ambigous “.json” extension. Would “/foo.json” mean that the data is of type application/vnd.hal+json or maybe application/vnd.api+json? Who knows?
IMO, file name extensions do not belong in URLs. URLs were never meant to be files, and we should try to avoid .html, .cgi and .php in our URLs. See also Cool URIs don't change from 1998: https://www.w3.org/Provider/Style/URI
Re: Best Practices for Designing a Pragmatic RESTful API
#5An API that uses the Link header can return a set of ready-made links so the API consumer doesn't have to construct links themselves. This is especially important when pagination is cursor based.
In the header is nice because then there’s no need to parse the payload to get the next page. But better still is to avoid cursor based pagination. Instead give me a cheap endpoint to get the total number of results and the configured max results per page and have constructable urls. (E.g. “?page=4” or “?offset=500”). This way generating all the urls can be a completely separate process from pulling the results.
Re: Best Practices for Designing a Pragmatic RESTful API
#6If you're interested in API design the upcoming RFC standard might be of interest: https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis-06
While this link is very interesting, its advice doesn’t seem to completely pertain to the kind of “single deployment” APIs most of us are probably making.
From the draft: “This document specifies best practices for writing specifications that use HTTP to define new application protocols, especially when they are defined for diverse implementation and broad deployment (e.g., in standards efforts).”
That’s not to say there aren’t useful ideas here (I found it very interesting in its own right), but the provisions against fixed URL schemes is followed by no commercial HTTP API I’ve ever seen.
Re: Best Practices for Designing a Pragmatic RESTful API
#7Anything that includes put patch delete is not pragmatic. Changes have side effects in any nontrivial system, making the semantic goal little more than wishful thinking. As others (even within the first few comments) figure out, being able to specify every mutable element from a GET is the most pragmatic quality of a modern web api.
Re: Best Practices for Designing a Pragmatic RESTful API
#8gzip + ssl is still (and will always be) a risky choice, isn't it?
Do any of the newer compression algorithms fix that problem?
Re: Best Practices for Designing a Pragmatic RESTful API
#9gzip + ssl is still (and will always be) a risky choice, isn't it? Do any of the newer compression algorithms fix that problem?
It depends.
The problem was that SSL supported compression directly, so you could compress the encapsulated stream. What happens in HTTP is that, say the cookie header contained the user's session cookie, and the body was somewhat controllable by an attacker. (E.g., by making CORS requests in the background.) The attacker could repeat "Cookie: auth=a" many times; if your auth cookie started with "a", it would compress slightly better as both could get compressed together, things would be slightly faster, and an attacker could use timing information to discern that he'd gotten the first character correct, and move on to the second.
See: https://en.wikipedia.org/wiki/CRIME
HTTP compression being mentioned in the article only compresses the body. It's still possible to execute the same sort of attack situationally if there's some part of, say, a response body that an attacker can control and a part that response body that the attacker doesn't control and is sensitive and wants to know and somehow only has access to the timing information.
While there is a Wikipedia article on this variant ("BREACH"), I think this is more informative: https://security.stackexchange.com/questions/20406/is-http-c... ; it lists a decent example of trying to get at a CRSF token.
But generally, JSON responses don't mix secret data + attacker controllable data, I feel, so compression should usually be okay. (And IME, it's typically done.) SSL/TLS compression should usually be left off, as that seems much easier to exploit.
Re: Best Practices for Designing a Pragmatic RESTful API
#10An API that uses the Link header can return a set of ready-made links so the API consumer doesn't have to construct links themselves. This is especially important when pagination is cursor based. In the header is nice because then there’s no need to parse the payload to get the next page. But better still is to avoid cursor based pagination. Instead give me a cheap endpoint to get the total number of results and the…
That's indeed the nicer way of paginating, but it breaks if the underlying resultset changes between requests. Which is exactly when cursor based pagination is generally used.