Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Best Practices for Designing a Pragmatic RESTful API

vinaysahni.com

Post reply on HN
Print view View original

31–38 of 38 posts

Re: Best Practices for Designing a Pragmatic RESTful API

#31

Post by Supermancho »

Bombthecat wrote: post #13
wwweston wrote: post #11

Earlier quoted context omitted.

Using Accept headers is the right thing, for the reasons you specify, and also the additional reason that they allow for the client to specify a list of possibilities that can be negotiated down to a result (server doesn't understand `application/vnd.hal+json`? maybe it can still send you `application/json`). That said: the extension-implies-media-type approach may not be right for an application server that renders…

Also, rest is interesting because it solves a lot of "base protocol" questions. Accept header is part of standard http. So that should be the default way.

That isnt a problem. Your API docs are the solution. Mapping communication protocols on to your applicarion for zero benefit over any other strategy. Yhis idea has been a hindrance at various cargo cult teams for decades. At least the RFC doesnt try to fool others into the fantasy.

Re: Best Practices for Designing a Pragmatic RESTful API

#32

Post by [deleted] »

bradleyjg wrote: post #27
caseysoftware wrote: post #26

Earlier quoted context omitted.

+1 to what your other response said You have to remember the goal of pagination: to move through a collection of results sequentially. If your underlying page is constantly changing (as the other response noted), then you have NO way to know what should be your next intended offset/page to move either or back. A simple sort with "results always go here" seems like a good approach but now you're packing additional und…

If the underlying data is constantly changing, how do cursors solve that problem? The only guarantee I get asking for the next page after a given item is that it won't contain the last item I've already seen. There's no other inherent guarantees. The page could contain all items I've already seen, early pages (in this new version of the underlying dataset) could have items I've never seen, and so on. It's as arbitrar…

[deleted]

Re: Best Practices for Designing a Pragmatic RESTful API

#33

Post by rumanator »

PretzelFisch wrote: post #30
rumanator wrote: post #20

Regarding API versioning, FTA: > There are mixed opinions around whether an API version should be included in the URL or in a header. Academically speaking, it should probably be in a header. However, the version needs to be in the URL to ensure browser explorability of the resources across versions (remember the API requirements specified at the top of this post?). I don't see how this is relevant with a RESTful API…

When you see versioning it's a pretty good hint that they use is as a buzz word and it's just RPC wrapped in REST clothing

RPC-over-HTTP passed off as REST is indeed a nuisance but unfortunately that doesn't get rid of the need to support multiple versions of the same API, specially if you don't control which clients are consuming your services.

Re: Best Practices for Designing a Pragmatic RESTful API

#34

Post by detaro »

teddyh wrote: post #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 solv…

If "browser explorability" is important, this article fails to discuss it properly when it comes to authentication, too.

Re: Best Practices for Designing a Pragmatic RESTful API

#35

Post by injb »

It's worth reading, but his arguments against using hyperlinks are vague and frankly weak. He says there's not much to be gained because you can't make "significant" changes without breaking client code; that may be true for certain values of "significant", but the bottom line is that you can change a lot more without breaking clients if you use hyperlinks everywhere, than if you don't.

It's not totally clear what he means by "not ready for prime time" but HATEOS has been achieving what it was designed for for a long time - that is, reducing the interdependence between client and server code.

It's also worth noting that using server-generated links everywhere eliminates the need for an entire category of documentation, and makes debugging much more pleasant and efficient (especially when the person debugging didn't write either the client or the server code).

Honestly, if there's one feature that determines whether an API should be described as RESTful or not, it's this. Think very carefully before building an API that requires the client to know how to build URLs!

Re: Best Practices for Designing a Pragmatic RESTful API

#36

Post by ptman »

bradleyjg wrote: post #5

An 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…

How about keyset pagination instead of limit & offset? https://use-the-index-luke.com/no-offset

Re: Best Practices for Designing a Pragmatic RESTful API

#38

Post by bradleyjg »

ptman wrote: post #36
bradleyjg wrote: post #5

An 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…

How about keyset pagination instead of limit & offset? https://use-the-index-luke.com/no-offset

I don’t like it because it introduces a linear dependency for every step on the ingest on the all the prior steps.

It’s convenient for the server but not the client.

Post reply on HN