How to (and how not to) design REST APIs • Hacker News Board

Re: How to (and how not to) design REST APIs

#31

Post by teaearlgraycold » Wed, Nov 01, 2023, 9:17 PM UTC

throw_m239339 wrote: post #22

teaearlgraycold wrote: post #7

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

To be fair I was being a tiny bit inflammatory. I think it's appropriate to use HTTP codes sparingly. Personally I'll use 401 and 500 but everything else is 200. And if the API is meant for public consumption by 3rd party devs then meeting expectations is more important than my personal philosophy.

But basically the overlap between the classic HTTP status codes and your API's functionality is IMO coincidence. Unless you're building a BLOB store or HTTP middleware you probably do not have enough overlap for it to be truly appropriate for your domain. HTTP is the envelope. It doesn't need to mix with your custom JSON API.

Re: How to (and how not to) design REST APIs

#32

Post by iterati » Wed, Nov 01, 2023, 9:20 PM UTC

robertlagrant wrote: post #14

AlexandrB wrote: post #6

Found 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} But then in Rule 2: GET /shop/{shop_id}/listings # normal, expected Shouldn't that be "/shops/{shop_id}/listings"? Or is it plural only if you can actually GET the path (i.e. there's no GET for just "/shop") and otherwise it should be sing…

Plural or singular seems far too marginal to be good or bad. I use singular.

Same. My table names are also singular.

Re: How to (and how not to) design REST APIs

#33

Post by fsaintjacques » Wed, Nov 01, 2023, 9:23 PM UTC

I highly recommend anyone to read Google's [AIP](https://google.aip.dev/). There's even a grpc schema linter for it. Put more focus on the resource data design than nitpicking on transport details. I would consider the best lessons to be:

- Optional but supported user defined identifiers, it's so frustrating to work with API that passes you back an identifier.

- String identifier (names) for resources, with some kind of type namespacing, i.e. the prefix in the author's document - Consistent set of fields (create_time, update_time, annotations, ...)

- Avoid dynamic map (this is a JSON self-inflicted wound)

Re: How to (and how not to) design REST APIs

#34

Post by RedShift1 » Wed, Nov 01, 2023, 9:23 PM UTC

sigmonsays wrote: post #16

are we beating a dead horse here? Havn't we talked about building REST APIs enough yet?

Hello there. Have you heard of our lord and savior, GraphQL?

Re: How to (and how not to) design REST APIs

#35

Post by DSMan195276 » Wed, Nov 01, 2023, 9:23 PM UTC

switch007 wrote: post #5

Some 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…

> Anything in your stack can return any HTTP error code - I don't see why 404 is special.

I'm surprised you don't - in my experience 404's are by far the most common response to get when you haven't wired things up correctly. Sure anything in the stack _can_ return any code and response they want, but you're still much more unlikely to come across a 410 rather than 404. If that unlikeliness saves you support calls down the line then that's pretty good.

Re: How to (and how not to) design REST APIs

#36

Post by stickfigure » Wed, Nov 01, 2023, 9:23 PM UTC

pavlov wrote: post #29

stickfigure wrote: post #19

Earlier quoted context omitted.

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.

Yes, I would expect GET /students to return all of the students (or at least, all of the students visible to me). Typically with query parameters for filtering:

    GET /students?min_age=20

Alternatively, `students` might be a collection attribute on another resource:

    GET /classes/{class_id}/students

Re: How to (and how not to) design REST APIs

#37

Post by 3cats-in-a-coat » Wed, Nov 01, 2023, 9:26 PM UTC

We need to forget this word REST, because all advice about it is superlame, regardless of the original paper.

Re: How to (and how not to) design REST APIs

#38

Post by alxmng » Wed, Nov 01, 2023, 9:27 PM UTC

“RESTful” API design is mostly bike-shedding.

There’s no standard. Every REST API looks different. Clients have to refer to documentation anyway, so consistent URL patterns achieve nothing. People waste large amounts of time over totally inconsequential minutiae like whether to use singular or plural words in URLs.

Separating idempotent calls from non-idempotent calls is useful, but REST overcomplicates this. All that’s needed is read and write calls, yet REST has get, post, patch, put, delete…

REST is also inefficient. Clients could read the data they need in one HTTP request, but most “RESTful” APIs force clients to make many requests for the sake of what is essentially aesthetics.

Re: How to (and how not to) design REST APIs

#39

Post by tkiolp4 » Wed, Nov 01, 2023, 9:27 PM UTC

lmz wrote: post #12

541 wrote: post #4

Earlier quoted context omitted.

Care to elaborate briefly on why they do?

"REST" is supposed to be an architectural style reflecting the Web as used by humans. Humans don't normally manually construct URLs. They navigate based on links from an entry point. (See also: https://hypermedia.systems/hypermedia-components/#_self_desc... )

The vast majority of people using REST do not follow its original definition, so the original definition doesn’t matter anymore.

It’s like human languages: REST is whatever we make of it, regardless of what academics say.

Re: How to (and how not to) design REST APIs

#40

Post by bonzini » Wed, Nov 01, 2023, 9:28 PM UTC

stickfigure wrote: post #19

elevation wrote: post #9

Rule #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

"POST /students" is a create action, but verbs are fine for individual entities, for example "POST /students/ID/enroll".