5 ms·

Rule #1 is terrible advice. Avoid plural nouns in English API endpoints because English is full of irregular plurals. For example: goose -> geese child -> ch

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 anyway (POST api/student/create), and adding the plural means doubling the API route namespace. It's cleaner and simpler to stick with singular nouns.

marcellus23 3y ago
> for a CRUD interface you may need the singular form anyway (POST api/student/create) Why? What's wrong with api/students/create? > Avoid plural nouns in English API endpoints because English is full of irregular plurals. I don't buy this. I mean, yes, it's true, but how often do people really need to write these endpoints after initially writing the client code?
- rswail 3y ago
  Verbs in a URL are an API "smell" for me. URLs refer to a resource that you can manipulate. What resource is /students/create referring to?
stickfigure 3y ago
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.
takinola 3y ago
You really should not include the action in the URL ie rather than GET api/student POST api/student/create DELETE api/student it should be POST api/students GET api/students DELETE api/students
golergka 3y ago
It gets even more unpredictable for everyone involved when it's a non-native speaker who writes the API schema.
plugin-baby 3y ago
> index -> indices vertex -> vertexes I guess it’s in support of your point, but if you’re going to pluralise index as “indices”, why wouldn’t you use “vertices” for vertex?

marcellus23 3y ago

> for a CRUD interface you may need the singular form anyway (POST api/student/create) Why? What's wrong with api/students/create? > Avoid plural nouns in English API endpoints because English is full of irregular plurals. I don't buy this. I mean, yes, it's true, but how often do people really need to write these endpoints after initially writing the client code?

rswail 3y ago
Verbs in a URL are an API "smell" for me. URLs refer to a resource that you can manipulate. What resource is /students/create referring to?

stickfigure 3y ago

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.

takinola 3y ago

You really should not include the action in the URL ie rather than GET api/student POST api/student/create DELETE api/student it should be POST api/students GET api/students DELETE api/students

golergka 3y ago

It gets even more unpredictable for everyone involved when it's a non-native speaker who writes the API schema.

plugin-baby 3y ago

> index -> indices vertex -> vertexes I guess it’s in support of your point, but if you’re going to pluralise index as “indices”, why wouldn’t you use “vertices” for vertex?