15 ms·

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

pavlov 3y ago
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.
- stickfigure 3y ago
  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
- zdragnar 3y ago
  I expect singular to return one, and plural to return a set, which could range from 0...n. Likewise, I wouldn't expect a singular to return a single object wrapped in an array, but I would always expect "/plural" (with no further qualifier in the url) to return an array, regardless of 0, 1 or more results. Why would returning a full set be a condition of whether or not plural is ambiguous?
bonzini 3y ago
"POST /students" is a create action, but verbs are fine for individual entities, for example "POST /students/ID/enroll".
- rswail 3y ago
  I use Nouns exclusively in APIs, not verbs. URLs define resources. Resources are (99% of the time) Nouns. So POST /students/{id}/enrollment Or POST /students is the act of enrolling a student, so the returned Location might be /students/{id}/enrollment to reflect the current state of that resource. The other details of the student might be at URLs like /students/{id}/details, /students/{id}/results, /students/{id}/courses etc etc If I end up having part of a "sub-resource" in the "main" resource, then I try to always have an href, otherwise you have to put all of the information. So GET /students/{id} might return a JSON object with an embedded "enrollment" object, but that embedded object would have an href to the full enrollment resource.
3cats-in-a-coat 3y ago
An API is not an essay, in OOP you write Array<Student> and not Array<Students> 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 other conditions such as `GET /student/top` or `GET /student/graduated` and then all students will be just the filter "all" or: `GET /student/all`. As for `POST /student/create`... it doesn't matter. To use one of 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.
- hnbad 3y ago
  > 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.
  - rswail 3y ago
    In HTML, you could have a FORM with the URL of /lamp/switch that you PUT.
    - 3cats-in-a-coat 3y ago
      So you're putting a switch. Great API design.
    - cxr 3y ago
      PUT is not a valid method from an HTML form. Only GET or POST are permitted.
      - 3cats-in-a-coat 3y ago
        This kind of reveals a little secret of many of the REST gurus. They have no clue what they're talking about.
jordanrobinson 3y ago
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 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 the path.
- stickfigure 3y ago
  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.
prisonality 3y ago
how do you differentiate between plural vs singular of: `GET /staff` ?
- stickfigure 3y ago
  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.
  - prisonality 3y ago
    what's your opinion of using suffix like '_list' to differentiate it ? ie: GET /species and GET /species_list ?
    - stickfigure 3y ago
      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.
    - bonzini 3y ago
      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.

pavlov 3y ago

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.

stickfigure 3y ago
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
zdragnar 3y ago
I expect singular to return one, and plural to return a set, which could range from 0...n. Likewise, I wouldn't expect a singular to return a single object wrapped in an array, but I would always expect "/plural" (with no further qualifier in the url) to return an array, regardless of 0, 1 or more results. Why would returning a full set be a condition of whether or not plural is ambiguous?

bonzini 3y ago

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

rswail 3y ago
I use Nouns exclusively in APIs, not verbs. URLs define resources. Resources are (99% of the time) Nouns. So POST /students/{id}/enrollment Or POST /students is the act of enrolling a student, so the returned Location might be /students/{id}/enrollment to reflect the current state of that resource. The other details of the student might be at URLs like /students/{id}/details, /students/{id}/results, /students/{id}/courses etc etc If I end up having part of a "sub-resource" in the "main" resource, then I try to always have an href, otherwise you have to put all of the information. So GET /students/{id} might return a JSON object with an embedded "enrollment" object, but that embedded object would have an href to the full enrollment resource.

3cats-in-a-coat 3y ago

An API is not an essay, in OOP you write Array<Student> and not Array<Students> 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 other conditions such as `GET /student/top` or `GET /student/graduated` and then all students will be just the filter "all" or: `GET /student/all`. As for `POST /student/create`... it doesn't matter. To use one of 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.

hnbad 3y ago
> 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.
- rswail 3y ago
  In HTML, you could have a FORM with the URL of /lamp/switch that you PUT.
  - 3cats-in-a-coat 3y ago
    So you're putting a switch. Great API design.
  - cxr 3y ago
    PUT is not a valid method from an HTML form. Only GET or POST are permitted.
    - 3cats-in-a-coat 3y ago
      This kind of reveals a little secret of many of the REST gurus. They have no clue what they're talking about.

jordanrobinson 3y ago

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 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 the path.

stickfigure 3y ago
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.

prisonality 3y ago

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

stickfigure 3y ago
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.
- prisonality 3y ago
  what's your opinion of using suffix like '_list' to differentiate it ? ie: GET /species and GET /species_list ?
  - stickfigure 3y ago
    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.
  - bonzini 3y ago
    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.