How to (and how not to) design REST APIs

Re:How to (and how not to) design REST APIs by prisonality on Wednesday November 01, 2023 @06:24PM (#38106207)

how do you differentiate between plural vs singular of:

`GET /staff`

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by stickfigure on Wednesday November 01, 2023 @06:37PM (#38106351)

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.

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by prisonality on Wednesday November 01, 2023 @06:40PM (#38106382)

what's your opinion of using suffix like '_list' to differentiate it ?

ie:

GET /species

and

GET /species_list

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by stickfigure on Wednesday November 01, 2023 @07:21PM (#38106782)

Seems weird.

Of all the rules, #1 one is by far the most arbitrary and least important. But it's also a thoroughly established convention. If you want to present "this is a normal, boring API with few surprises" to your clients, I wouldn't recommend odd collection suffixes.

But it's not going to fundamentally change the usability of your API, unlike many of the other rules.

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by bonzini on Wednesday November 01, 2023 @08:00PM (#38107131)

The case of having a singular at the end of a GET is so rare that it should be easy to disambiguate. I have a project where one of the main objects is a "series", it's clear what "GET /series" and "GET /series/ID" means to anyone that has seen a REST API.

[ Parent | on HN ]