I always found this document by Microsoft very very good
https://docs.microsoft.com/en-us/azure/architecture/best-pra...
Best practices for REST API design (2020)
31–40 of 273 posts
Re: Best practices for REST API design (2020)
#32All 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…
For comprehensive APIs,GraphQL is often more performant. 1 request that takes 500ms is far better to 5 requests that take 200ms
Re: Best practices for REST API design (2020)
#33A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
From a client application perspective, would you want to handle the cases differently?
Of course, hitting a path without a handler is a bug, a resource which doesn't exist is a normal thing.
Re: Best practices for REST API design (2020)
#34I'd recommend against using `v1` in the path and prefer content negotiation: GET /resource/1 Accept-Version: ~1.0.2 ... Implementation-wise this ends up with better code (and less code) on the back-end and a reduced number of HTTP routes (which should represent the entities and be maintained). The pain of REST is that there's very little in terms of "correct" as we don't have a formal specification of the semantics.…
I'd recommend the opposite, as with a versioned URL you can very easily route stuff to different machines by simple URL inspection and have a very clean separation between versions.
Re: Best practices for REST API design (2020)
#35All 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…
> - Allow filtering, sorting, and pagination: yes, good luck coming up with the right query structure and sticking to it.
I believe that treating RESTful APIs as a smart data storage that can do advanced querying is a mistake, or rather REST is not the proper solution for this use case, and you did well to move on from it. Personally I've never failed to use REST successfully as long as I was willing to do proper caching, sorting and filtering in the API consumer. REST is plenty if you need presenting collections of things with key-set pagination and proper caching headers.
In the days of HTTP2+, it's easy to fire 100 concurrent requests to a key-set RESTFUL API and load all the data that you could ever need. :)
Re: Best practices for REST API design (2020)
#36Earlier quoted context omitted.
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…
> All things that GraphQL claims to do can be implemented in RESTful services easily. How do you easily write an endpoint that can either return a comment, a comment with its children, a comment with its corresponding story, with a strongly typed schema (ie. no optional children or story whatever the query is)?
like i said, specify what you want in the query params or in the request body
Re: Best practices for REST API design (2020)
#37Earlier quoted context omitted.
Isn’t 409 if you’re trying to update an existing record (PUT) and not create a new record (POST)? The ambiguity is probably why most people just use 400 and call it a day.
There's this, FWIW: https://i.stack.imgur.com/whhD1.png
Please tell me that's satire...
Re: Best practices for REST API design (2020)
#38> Then if we try to submit the payload with the email value that already exists in users, we’ll get a 400 response status code with a 'User already exists' message to let users know that the user already exists. With that information, the user can correct the action by changing the email to something that doesn’t exist. I was always under the impression that 409 would be the "correct" code here, while you'd use 400 i…
Ironically, your comment is a perfect illustration of one of the problems with REST - its tendency to provoke discussion about things that don't actually matter in practice. No user cares whether an error response came back with a 400 or a 409 status, or what those codes even mean. It's madness that as a profession we spend so much of our employers' time and money on trivial things that deliver no value whatsoever. R…
> No user cares whether an error response came back with a 400 or a 409 status
Unless your product is itself an API, your users shouldn't be exposed to its status codes. Sorry for dispensing trite advice, but you should really have a nice client between API and users, that can translate the difference between 400 and 409 statuses in a comprehensible and friendly way. :)
Re: Best practices for REST API design (2020)
#39I'd recommend against using `v1` in the path and prefer content negotiation: GET /resource/1 Accept-Version: ~1.0.2 ... Implementation-wise this ends up with better code (and less code) on the back-end and a reduced number of HTTP routes (which should represent the entities and be maintained). The pain of REST is that there's very little in terms of "correct" as we don't have a formal specification of the semantics.…
I'd recommend the opposite, as with a versioned URL you can very easily route stuff to different machines by simple URL inspection and have a very clean separation between versions.
Unless you're talking about a human dispatching the request (url toolbar or via tool like curl) There's nothing special between a url path or a content header
Either way it's layer 7 routing. What was the advantage again?
Re: Best practices for REST API design (2020)
#40Small typo-ish error in the article, emphasis mine:
> 401 Unauthorized – This means the user isn’t not authorized to access a resource.
Surely that should say that the user isn't not unauthorised?