Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to (and how not to) design REST APIs

github.com

Post reply on HN
Print view View original

61–70 of 153 posts

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

#61

Post by prisonality »

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

how do you differentiate between plural vs singular of:

`GET /staff`

?

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

#62

Post by layer8 »

DSMan195276 wrote: post #35
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 do…

With REST 404s due to missing resources (non-existing ID), you should generally get corresponding error information in the body (as also described in TFA), and clients should log/display that information. That should make enough of a difference. There’s a lot of “should” here, of course, but instead of teaching developers to not use 404, it would be better to teach them to create and handle error responses appropriately.

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

#63

Post by hnbad »

3cats-in-a-coat wrote: post #44
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

An API is not an essay, in OOP you write Array and not Array and yet you understand the type is about an array of students. Getting hung up on grammar in an API is probably the dumbest problem to have. If you think `GET /student` is confusing, or more importantly, structurally restrictive as an API, you can think about it as `GET /student/filter` where the "filter" may be a specific student id, or a range of ids, or…

> Fielding's own examples from his blog, how'd you turn a lamp on and off via REST? Would you be like `POST /lamp`? No. It's unclear WTF is happening.

No, of course you'd be like `PATCH {"light": "off"} /lamp`!

Kidding of course but it's true that REST purity does not make for intuitive APIs in complex real-world problem domains.

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

#64

Post by stickfigure »

jordanrobinson wrote: post #50
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

While I do agree with this in almost all cases, I have found scenarios where there are actions that don't map easily to a HTTP verb and need something more explicit. What I've generally done in these cases is pretty similar to https://cloud.google.com/apis/design/custom_methods which also explains the problem better than I can. I'd be interested as to how you'd solve some of these problems without an explicit verb in…

I'm not a purist; for unusual edge cases, I'll put a verb (or something appropriate to the context) at the end of the path. But `create` isn't unusual, just POST to a collection.

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

#65

Post by jameshart »

This falls down as soon as it makes a fundamental misunderstanding of what makes a REST api into a REST api.

It gives this as a ‘bad’ example:

   GET /v3/application/shops/{shop_id}/listings/{listing_id}/properties
With the justification that “The {listing_id} is globally unique; there's no reason for {shop_id} to be part of the URL. “

No the point of the API is that /v3/application/shops/{shop_id}/listings/{listing_id}/properties is a globally unique identifier. Your belief that parts of that id have global meaning outside the context of that identifier is irrelevant - that path is the identifier for the resource.

And having hierarchical paths is useful because you can do things like manage permissions on parts of the hierarchy - users might have permission to check listings in certain shops and we can characterize that as them having permission on /v3/application/shops/{shop_id}/listings/*.

Directory structures of resource identifiers are good and logical and not a ‘bad’ API design practice at all. You might as well argue the UNIX file system is a bad design because all the files have a unique inode id so paths are completely unnecessary.

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

#67

Post by layer8 »

esafak wrote: post #59
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…

> Some good points - particularly about not returning arrays. I don't get that one; why is an object with an array property more evolution friendly than an array of objects?

Because you can add new properties for response-level global information on an object, but not on an array.

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

#68

Post by esafak »

layer8 wrote: post #67
esafak wrote: post #59

Earlier quoted context omitted.

> Some good points - particularly about not returning arrays. I don't get that one; why is an object with an array property more evolution friendly than an array of objects?

Because you can add new properties for response-level global information on an object, but not on an array.

Obviously if it was global, but if not, you'd include it in the objects in the array, no? This is not a question of schema evolution per se.

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

#69

Post by stickfigure »

prisonality wrote: post #61
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

how do you differentiate between plural vs singular of: `GET /staff` ?

I don't? It's fine. I'm also fine just adding an 's' to many words that have unusual plurals; English is flexible, and "persons" is a perfectly acceptable substitute for "people".

That said, I don't love your example. Staff does have a plural, staffs - as in, the separate staffs of multiple organizations.

Post reply on HN