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

91–100 of 273 posts

Re: Best practices for REST API design (2020)

#91

Post by dec0dedab0de »

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 with forms for posts and whatnot.

Re: Best practices for REST API design (2020)

#92

Post by motogpjimbo »

bickeringyokel wrote: post #77
motogpjimbo wrote: post #54

Earlier quoted context omitted.

That's the purpose of an error message isn't it? I'm not sure what an HTTP response code is adding to that. In my experience, in any situation where you produce an API where you want the client to pay close attention to the actual error that occurred, the list of official HTTP response codes is generally woefully inadequate for the task and you're going to want to work with something much more specific. If my payment…

Let me get this straight, you don't think codes matter, but you want to manage a giant proptietary list of codes? Won't you just send up in those huge discussions you waste so much time on?

To continue the payment processor example, if there are 10 different reasons for declining a transaction, how do you propose mapping those onto 4xx codes? Would you just choose 10 at random? Or would you just return, e.g., E_INSUFFICIENT_FUNDS?

Re: Best practices for REST API design (2020)

#93

Post by Scarbutt »

profquail wrote: post #88
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.

You can also use SQL:2011 "System-Version Tables" (a.k.a. temporal databases) supported in most of the major RDBMSs now. You'd just need to keep track of a timestamp when you started querying/paginating and include it as part of the SQL query, which'll give clients a consistent view even if the database is being concurrently modified.

temporal databases) supported in most of the major RDBMSs now.

Which ones?

Re: Best practices for REST API design (2020)

#94

Post by n_e »

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…

> On the flip side, I've never been frustrated by getting too many fields back from an API

A pretty common use-case I have is needing to support these three things :

- A “big object” list screen (where retrieving the whole objects would make the query return megabytes off data)

- A “big object” details screen (where I need the full object)

- Programmatically getting many big objects

With GraphQL it involves writing one (or two) straightforward queries, while with REST it would require more thought or code.

Re: Best practices for REST API design (2020)

#95

Post by jrockway »

packetlost wrote: post #80
mhoad wrote: post #57

Earlier quoted context omitted.

My original comment might have given the impression that I was some gRPC guru when in reality I’ve only played with it very briefly. What are the versioning problems with it? I was under the impression that it was actually designed from the start to be fairly flexible with regards to changing API methods etc

Well I wasn't referring to API versioning, I was referring to the actual lib versioning. All of Google runs basically at HEAD and nearly all of their libraries reflect this. In a distributed system, if you update one of the GRPc library versions, you need to update all of them otherwise you can run into weird failures.

That might be true, but at least when I was at Google, people were not building and releasing their software to pick up HEAD of libraries they depended on. Some binaries running in production could be quite old and seemed to communicate with newer builds just fine. (I suppose if there was a problem someone would have built a new version, though.)

Re: Best practices for REST API design (2020)

#96

Post by Naac »

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.

What does Hackernews use in this case?

Re: Best practices for REST API design (2020)

#97

Post by mgkimsal »

Scarbutt wrote: post #93
profquail wrote: post #88

Earlier quoted context omitted.

You can also use SQL:2011 "System-Version Tables" (a.k.a. temporal databases) supported in most of the major RDBMSs now. You'd just need to keep track of a timestamp when you started querying/paginating and include it as part of the SQL query, which'll give clients a consistent view even if the database is being concurrently modified.

temporal databases) supported in most of the major RDBMSs now. Which ones?

I'm only aware of SQL Server (2016), Oracle and MariaDB supporting temporal tables, and... having dived in to them, they can certainly add some complexity to your data and queries. Would be happy to learn of more - had to do some digging on this in late 2019 for a PostgreSQL project, but there's nothing native or 'standard' for pg at that point in time.

Re: Best practices for REST API design (2020)

#98

Post by gengstrand »

fc373745 wrote: post #9
throw_m239339 wrote: post #6

All these "best practices" are exactly why I embraced GraphQL quickly and flushed "REST" down the toilets for big projects (http+json is fine for small ones, since no lib overhead). GraphQL is unashamedly the new SOAP. I.e. we have a spec, not a series of "best practices" thus endless architectural debates where people are shamed for 'doing it the wrong way' online. - Accept and respond with JSON: No, why? what if I…

Never understood the hype around GraphQL. You want to know how to halve your performance and responses/s on your service? add graphql. All things that GraphQL claims to do can be implemented in RESTful services easily. If you want specificity in your query fetching, just add query params or put them in the request body If you want schema validations, there are many libraries that help you with that. And if you want d…

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

The TL;DR of that blog is this. There isn't much value that GQL can provide over REST + OpenAPI. GQL is still in its infancy so APM is easier with REST. The biggest argument for GQL is returning the right amount of data but GQL is slightly slower than REST because the server is having to parse what is essentially a mini program with every request.

Re: Best practices for REST API design (2020)

#99

Post by dec0dedab0de »

Longwelwind wrote: post #48
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…

What is the usefulness of this feature? The only advantage I see is that your clients can choose the format they want to work with, but since the serialization format is just a message format that has no impact on the code, and that most of them have a bijective transformation between them, I don't see the point. If it feels like a lot of work (Or the added complexity of a moving part, if using the tool you linked) f…

things like this are useful if you have a user that is integrating your api into some kind of legacy application that does not support json. Then in the future when JSON goes out of style, you could easily add support whatever the new format is.

Re: Best practices for REST API design (2020)

#100

Post by the_arun »

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…

We could support "fields" query parameter in REST API to get only necessary attributes. Eg. ?fields=f1,f2,f3 etc.
Post reply on HN