Liked the idea of using wiki as blog
he actually writes about that. I happen to like it too.
https://github.com/stickfigure/blog/wiki/GitHub%27s-wiki-mak...
How to (and how not to) design REST APIs
21–30 of 153 posts
Re: How to (and how not to) design REST APIs
#22Regarding #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.
> Regarding #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.
What is an application error? If a user tries to query a ressource they are not authorized access to, then returning a 401 is appropriate, if the resource doesn't exist then 404 is also appropriate, in theory (maybe not in practice for security reasons but whatever). Nothing wrong with that.
HTTP codes are not made only for routers, caches and proxies, HTTP was made for user agents such as browsers, HTTP is one of the foundations of REST.
and I didn't downvote you, I'm just asking a question.
Re: How to (and how not to) design REST APIs
#23Some 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.
The problem is that the support call comes in as "your DELETE call isn't actually deleting". Sure it's not your fault, but it imposes a cost on you to investigate. And of course the first time you go directly to RTFM without checking will be the time it actually is your bug.
404 is special because it's so incredibly common. Why take the risk? There are other perfectly good error codes that - in practice - don't have this issue.
Re: How to (and how not to) design REST APIs
#24Re: How to (and how not to) design REST APIs
#25Experienced point 6 with the GitHub API. “Repository” is a core Git(Hub) primitive, and across the entire API surface (they have an OpenAPI spec, 40 MB in size total), last I counted it was 48 different versions of repository. For example, what’s considered a repo owned by a user might be different from that of an organisation. There is no sane recourse but automatic code generation, which is a ton of effort in itself (tooling isn’t great).
Re: How to (and how not to) design REST APIs
#26> REST APIs
"You keep using that word. I do not think it means what you think it means".
Re: How to (and how not to) design REST APIs
#27I feel like at this point I have heard convincing arguments for and against basically every point in this article, every article like it, and every comment on them.
Hot take: it doesn't matter. If the user cared enough about your decisions to file a bug report or a complaint, you're doing something right. Consider that a success.
Stop trying to shoehorn a creative outlet into your day job. Pick someone else's terrible design and stick to it.
Frankly I am shocked to see an article on REST design on HN in 2023. We sort of figured this one out.
Re: How to (and how not to) design REST APIs
#28Regarding #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.
I don't know why you're being downvoted. I think you're completely wrong, but it's not like you're being rude about it.
Status codes are not necessarily useful for the developer directly, as they're a second channel for the same information, but they are useful for middleware of all kinds (your argument applies equally to browsers showing errors to users, and the same counterarguments apply to programmers). For example, the HTTP library I'm using has an error_for_status function which conveniently raises a runtime error, without me having to dig into the response to do that manually. Also, if you invent more kinds of errors later, or even if you just haven't published a master table of errors where I can see it, the status code will still let me extract useful semantic information out of an error kind my code has not been written explicitly to handle.
Re: How to (and how not to) design REST APIs
#29Rule #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 a…
You use plurals anyway to fetch collections: GET /students So you can't escape the problem unless you want `GET /child` to fetch multiple children. Also, you should avoid verbs in URLs (IMHO, of course). You're adding to the students collection, so post to students: # BAD POST /student/create # GOOD POST /students
Does “GET /students” return all the students in the system? Probably not.
So in fact you’re fetching some subset of students anyway, and the size of the returned set might be one or zero depending on your query.
Given that, “GET /student” seems just as meaningful because neither the singular nor the plural can fix the ambiguity about what you’re actually getting.
Re: How to (and how not to) design REST APIs
#30are we beating a dead horse here? Havn't we talked about building REST APIs enough yet?
unequivocally