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

161–170 of 273 posts

Re: Best practices for REST API design (2020)

#161

Post by tshaddox »

kaoD wrote: post #71
ngrilly wrote: post #65

Do not use a page argument for pagination. If you have another process/client concurrently adding/removing items, then some items will be returned twice, and others will never be returned. It is better to use, for example, the ID of the last returned item as a starting point for the next query.

As a user I expect that to happen. Cursors on the other hand are awful for getting to arbitrary pages, they are mostly useful for "More" links as on HN or Reddit. It's a trade-off.

The notion of "page" really only applies as an arbitrary interface division to make performance predictable. The same book could be published in different form factors such that there's no real meaning to a specific page number. There's no "turn your bibles to page 112." That's even more clearly true when the data itself is changing over time, such that even the first thing on the first page is changing over time.

Thus using page numbers is probably a pretty poor proxy for what you're actually trying to do when you say "getting to arbitrary pages." Presumably you are wanting to skip to a specific place in the list, perhaps specified as a percentage ("take me halfway through the list") or as some predicate on the data ("take me to items from 2 weeks ago"). APIs should provide ways of expressing these specific places in a list, instead of requiring you to either guess page numbers or do extra work to calculate them.

Re: Best practices for REST API design (2020)

#162

Post by pc86 »

lhorie wrote: post #158
ngrilly wrote: post #146

Earlier quoted context omitted.

> If items get returned twice while iterating, then I know something got added. Fair point. I agree, that's a nice side effect. But what if you're looking at page 1, and an item is removed from that page? Then you'll never see the first item at page 2, because it's now the last on page 1. > Then if I want a slice from 300-8000th items, I can type exactly that in the URL. That's a nice feature. But it can put a lot of…

> an item is removed How common are concurrent removals in practice though? 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" > it can put a lot of load on your backend if you paginate over 10 of thousands of items Look at it in aggregate. Fiddling w/ URL params to pagina…

> 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.

Re: Best practices for REST API design (2020)

#163

Post by tshaddox »

_nothing wrote: post #113
tstrimple wrote: post #102

Earlier quoted context omitted.

How often do people really jump to an arbitrary page? I'd say filtering / searching capabilities are far more important for users than paging.

It depends? If I'm looking for a new desk on IKEA's online catalog then I care more about filtering/searching, but if I'm reading through a conversation on a forum and want to be able to link to certain sections then I want that paginated.

But even for the latter case, surely you're not specifically interested in a specific page called "page 50" but rather you're interested in items satisfying some predicate (like "posts from 2 weeks ago") or locations respective to the entire list (like "halfway through the list"), and it would be much better if the user interface supported those sorts of navigation.

Re: Best practices for REST API design (2020)

#164

Post by incrudible »

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 anyway. We'll keep doing it that way. You're going to have to accept it.

Re: Best practices for REST API design (2020)

#165

Post by ehutch79 »

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…

Send ISO date/time in utc.

Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it.

Send both an error code, and a string in simple english, or whatever your most common developer language is.

If you care about only updating certain fields, track changes and only send those fields to the backend.

These arn't really that hard.

Re: Best practices for REST API design (2020)

#166

Post by incrudible »

CharlesW wrote: post #156
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…

We could use a name for "standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries". So what shall we call REST without HATEOAS[1]? "RESTless"? [1] https://en.wikipedia.org/wiki/HATEOAS

No, a truly RESTless API must do away with all the other pointless HTTPisms in REST. If you're using any other method than GET or POST, or any other codes than 400 and 200, you're not truly RESTless.

Re: Best practices for REST API design (2020)

#167

Post by lhorie »

pc86 wrote: post #162
lhorie wrote: post #158

Earlier quoted context omitted.

> an item is removed How common are concurrent removals in practice though? 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" > it can put a lot of load on your backend if you paginate over 10 of thousands of items Look at it in aggregate. Fiddling w/ URL params to pagina…

> 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, what happens to commit history pagination in github's implementation if I rewrite git history? Chibicc for example deliberately rewrites its history for didactic purposes.

Re: Best practices for REST API design (2020)

#168

Post by simiones »

n_e wrote: post #108
fc373745 wrote: post #75

Earlier quoted context omitted.

it's just a hit to the db. Graphql works the same way if i'm not mistaken. and if its the case that you don't want the comments at all, then in the conditionals write your sql statements if you want comments select * from resource where id= some resource id if you don't select without comments from resource where id= some resource id there's no need to get into specifics, the point is graphql is not bringing anything…

I’m talking about the GraphQL or OAS schema. With a REST API, the “resource” type will always have an optional “comments” field, whatever the value of arg is. With a GraphQL API you’ll have the right type depending on your query.

If you truly care about that, the truly REST solution would be to define separate MediaTypes and use Accepts headers to specify which MediaType is desired.

So if you wanted comments you would send a request with a header like "Accept: application/resource_with_comments", and you'd send a Header like "Accept: application/resource_without_comments".

The thing is, few people want this level of control in practice. This would generally lead to a huge proliferation of types for very little practical benefit. Much simpler to have a set of well-defined types with optional fields than to define a new type for each combination of fields used today.

Re: Best practices for REST API design (2020)

#169

Post by gengstrand »

adamscybot wrote: post #124
gengstrand wrote: post #98

Earlier quoted context omitted.

I also wanted to understand why GQL was getting so much attention in a REST vs GraphQL way so I implemented a GQL microservice that had the same features as a service that I had implemented previously as REST. Both services ran on node.js and connected to the same data stores, etc. I ran both services on the same load test lab and documented my findings at https://glennengstrand.info/software/architecture/microservi.…

If you're a front end developer the advantages a clear because of much superior tooling. The reason for this the agreed SDL spec format which is part and parcel of GQL. REST is just a loose collection of ideas and OpenAPI is not integral to REST as theres no single over arching spec of organisation for REST. In my experence therefore, the tooing (code gen, doc gen) etc around OpenAPI is piss poor in comparison to gql…

The above referenced PoC service based on express uses https://github.com/apigee-127/swagger-tools which surfaces a web app by which front end devs navigate through the published API endpoints. They can use the web app to call the service via the endpoint or copy and paste sample code that calls the service. Most open api integrations support this kind of functionality.

Re: Best practices for REST API design (2020)

#170

Post by simiones »

adamscybot wrote: post #124
gengstrand wrote: post #98

Earlier quoted context omitted.

I also wanted to understand why GQL was getting so much attention in a REST vs GraphQL way so I implemented a GQL microservice that had the same features as a service that I had implemented previously as REST. Both services ran on node.js and connected to the same data stores, etc. I ran both services on the same load test lab and documented my findings at https://glennengstrand.info/software/architecture/microservi.…

If you're a front end developer the advantages a clear because of much superior tooling. The reason for this the agreed SDL spec format which is part and parcel of GQL. REST is just a loose collection of ideas and OpenAPI is not integral to REST as theres no single over arching spec of organisation for REST. In my experence therefore, the tooing (code gen, doc gen) etc around OpenAPI is piss poor in comparison to gql…

From my experience, front-end developers are the last people that want to learn how to query a complex data model. It's usually much preferable if the backend team exposes the required endpoints for any UI operation, since they have much more fine-grained control on the DB and a much clearer intuition on what is easy to do and what isn't.
Post reply on HN