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

Best practices for REST API design (2020)

stackoverflow.blog

Post reply on HN
Print view View original

191–200 of 273 posts

Re: Best practices for REST API design (2020)

#191

Post by NanoWar »

dec0dedab0de wrote: post #91
seliopou wrote: post #7

I interrupted my reading at 'Accept and respond with JSON' to write this comment, before I skipped over that section and returned to reading the rest. Folks that aren't aware of Webmachine should take a look: https://github.com/webmachine/webmachine The 'Accept' header should determine the response type, but content negotiation is something that few bother to implement. Webmachine does that for you, among other thing…

Django REST Framework has this built in, and is very easy to turn on. I always turn it on even though my users almost exclusively use json. I had one user use xml once, because they didnt know how to use json in whatever it was they were using. Noone has ever used yaml, but i leave it there just in case. if you do it right, using the standard html content type returns a human browseable representation of your api wit…

Omg I love the browsable api of Django. I am searching for something similar for .NET - any pointers anyone?

Re: Best practices for REST API design (2020)

#192

Post by NanoWar »

JimDabell wrote: post #74
danielovichdk wrote: post #50

Design is hard. In the given example we work with an Article domain. Where there are Comments. Fine and totally fair. But how would you design your object graph from the bottom up? Articles and Comments is a fairly simple example. Imagine a Transaction in bank domain context. Would you have an endpoint like so? transactions/:id/acoount/:id Or perhaps transactions/:id account/:id/transactions Whatever you pick you mus…

REST doesn’t really have the concept of endpoints. That’s a hierarchy some people artificially impose over the top of a REST system. REST doesn’t require it. All of your URLs could be randomised and a REST system would work exactly the same. You don’t need hierarchy in your URLs. If you want to load a transaction, then /transactions/123 is fine. If you want to load an account, then /accounts/456 is fine. You don’t ne…

This is true and I use top level URLs for all of my resources in a REST api. You can however to a POST to articles/:id/comments and return location headers pointing to /comments/:id easily!

Re: Best practices for REST API design (2020)

#194

Post by NanoWar »

Octoth0rpe wrote: post #56
nojvek wrote: post #44

I’d say REST apis should also support selections. E.g I only care about these fields. It’s the #1 reason why graphql is so popular. You only fetch what you want. But I have missed feelings about graphql. I wish they didn’t invent a new language, it was just json. I’ve encountered so many little bugs because graphql parsing is different between different servers. Ideas of graphql are great, implementation seems over c…

> It’s the #1 reason why graphql is so popular. You only fetch what you want. It's certainly one of the main sales points for graphql. On the flip side, I've never been frustrated by getting too many fields back from an API. I suppose if I was developing exclusively in extremely bandwidth limited contexts where getting back only 2 fields rather than 50 actually made a difference, I might care. It just seems like such…

You could simply use HAL with embedded resources in JSON. Not sure how the client side feels about that though

Re: Best practices for REST API design (2020)

#195

Post by ngrilly »

lhorie wrote: post #167
pc86 wrote: post #162

Earlier quoted context omitted.

> I can't think of a single instance off the top of my head where this is problematic and you can't just go back to the previous page if you're really paranoid or confused that something is "missing" The whole issue is that you're never going to know about it . Sure, you can write some convoluted automated process to double-check previous page(s) but most people aren't going to do that.

Sure, that's why I'm asking whether this is at all common. If the use case is programmatic, then just provide the ability to get an arbitrarily large set atomically (rather than forcing pagination size limits) and the problem goes away. Another thing to consider when paginating via id cursors: if the deleted item is the one your cursor is sitting on, then you no longer have a frame of reference at all. For example, w…

> just provide the ability to get an arbitrarily large set atomically

It's difficult to do in most HTTP deployments where we try to limit HTTP response duration.

> if the deleted item is the one your cursor is sitting on, then you no longer have a frame of reference at all

Not a problem. If your order your results by timestamp and ID, then you provide the timestamp and ID of the last item returned, and take anything after. Doesn't matter if the item is still there or not.

Re: Best practices for REST API design (2020)

#196

Post by saila »

incrudible wrote: post #164
saila wrote: post #133

This article doesn't mention linking at all, which is at the heart of REST. Without links, it isn't REST , and most of the suggestions don't have anything to do with REST per se . Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries. EDIT: To be clear, I don't particularly care if an API is "RESTful" or not, as long as it's well-designed and documented, but I th…

> This article doesn't mention linking at all, which is at the heart of REST. Please, just don't do it . Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying. > Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries. Yes, and we call that REST or RESTful a…

Interesting. I usually find it easier to generate URLs on the server and more convenient to consume APIs that include links to related resources.

The other option is munging URLs on the client side, which can be tedious.

I'm genuinely curious as to how including links in the response could make an API harder or more annoying to use.

Re: Best practices for REST API design (2020)

#197

Post by phtrivier »

With the exception of url naming (no rule, which is worse than any rule), error response (a bit ambiguous) and general verbosity, I find that the jsonapi.org spec can serve as a relatively sane default.

Although I would love for browsers to start natively supporting some sort of schema based, explicitly typed, binary format.

Re: Best practices for REST API design (2020)

#199

Post by phtrivier »

derkoe wrote: post #159

Most of these best practices forget the hard parts of JSON/REST APIs: - How to handle date and time incl. time zones - JSON has no data type for that - Handling of numbers (JSON only has double, which does not fit most cases) - Defined and parseable error responses (rfc 7807 plus extra fields for details) - Localization - do you send translated texts or just error codes? - How to handle updates? Overwrite every field…

There's and iso for dates as string with the offset, that's usually fine.

Handling Post and Patch differently can at least give a general guideline for "overwriting vs keeping fields on update."

The localisation part is trivial if you consider that APIs are to be consumed by machines - much harder, if you assume they're used for GUIs.

Error handling is easy to define right, but so tedious to implement....

1+n can be improved by "guessing" which nested ressources are going to be fetched, and include them "by default."

But you're right that those are decisions that need to me made, and can quickly be agonised on without adding much value....

Re: Best practices for REST API design (2020)

#200

Post by ngrilly »

dec0dedab0de wrote: post #180
ngrilly wrote: post #148

Earlier quoted context omitted.

That solves the problem of items added concurrently (by deduplicating them) but that doesn't solve the problem of removed items.

The only thing that completely solves for removed items is constantly polling, or setting up a webhook/callback of some kind. Padding the offset would solve for the problem mentioned where deleting an item would mean some non deleted items are not included in the paging results because they got moved up a page after that page was requested, but before the next page was requested. For example If I request 100 items at…

Your padding + deduplication solution is nice.

> Edit: If you used the ID of the last item instead of an offset, then you could get errors if your last item is in fact the one that was deleted.

If the items are sorted by ID, then we use the ID of the last item x. But for example if they are sorted by timestamp, then we use the timestamp of the last item (and maybe the ID to break ties). Then it doesn't matter if the last item is still there or not. We are only considering values before or after depending on the sort order.

Post reply on HN