How to (and how not to) design REST APIs
github.com
How to (and how not to) design REST APIs
1–10 of 153 posts
Re: How to (and how not to) design REST APIs
#2Liked the idea of using wiki as blog
Re: How to (and how not to) design REST APIs
#3Half of the points are complete bs. URLs don’t matter in REST. What matters are link relations.
Re: How to (and how not to) design REST APIs
#4Half of the points are complete bs. URLs don’t matter in REST. What matters are link relations.
Care to elaborate briefly on why they do?
Re: How to (and how not to) design REST APIs
#5Some good points - particularly about not returning arrays (I've made that mistake!)
But I feel 410 instead of 404 is pretty controversial:
> There are many layers of software that can return 404 to a request
Anything in your stack can return any HTTP error code - I don't see why 404 is special.
> When calling (say) GET /things/{thing_id} for a thing that doesn't exist, the response should indicate that 1) the server understood your request, and 2) the thing wasn't found. Unfortunately, a 404 response does not guarantee #1.
The server is free to return other codes for other classes of problems. The server could return 400 for a bad request, and leave 404 for "thing wasn't found", indicating it understood the request but it wasn't found.
Also surprised not to see RFC 7807 / RFC 9457 (Problem Details) not mentioned in the "structured error format" section.
Re: How to (and how not to) design REST APIs
#6Found a contradiction that I don't understand. From rule 1:
# GOOD
GET /products # get all the products
GET /products/{product_id} # get one product
# BAD
GET /product/{product_id}
GET /shop/{shop_id}/listings # normal, expected
Re: How to (and how not to) design REST APIs
#7Regarding #8 - just do not use http status codes for application errors. They are for routers, caches and proxies. Your application should pretty much only return 200 even on errors.
Edit: Bring on the downvotes. I will die on this hill.
Re: How to (and how not to) design REST APIs
#8Doing REST microservices is incredibly slow because of the amount of work it is to agree on what a "clean" and "consistent" api looks like for each service. It's just such an endless well of trying to establish best practices without refactoring constantly.
It's worth it for your public API, but it's such a huge time sink for internal APIs.
Re: How to (and how not to) design REST APIs
#9Rule #1 is terrible advice.
Avoid plural nouns in English API endpoints because English is full of irregular plurals. For example:
goose -> geese child -> children index -> indices vertex -> vertexes analysis -> analyses
This makes English plurals unpredictable especially for for non-native speakers and hurts API consistency and discoverability.
Also consider that for a CRUD interface you may need the singular form anyway (POST api/student/create), and adding the plural means doubling the API route namespace.
It's cleaner and simpler to stick with singular nouns.
Re: How to (and how not to) design REST APIs
#10Some good points - particularly about not returning arrays (I've made that mistake!) But I feel 410 instead of 404 is pretty controversial: > There are many layers of software that can return 404 to a request Anything in your stack can return any HTTP error code - I don't see why 404 is special. > When calling (say) GET /things/{thing_id} for a thing that doesn't exist, the response should indicate that 1) the server…
That rule is a hot take.
> You could use 404 but return a custom error body and demand that clients check for a correct error body. This is asking for trouble from lazy client programmers. It might or might not be "your fault" when clients see eventually inconsistent data, but the support calls they send you will be real.
Make sure that your 404 responses were always documented, then tell them to RTFM.