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.
I think just about anyone who uses a name referencing an Array<Student> will give it the name "students".
And it does often end up mattering, for clarity where at its use sites where you won't have the type declaration to help you out, and for having "student" available as a name in the same scope, as it's typical to pull an item out of a collection.
/student/all looks particularly icky to me. For getting a student, it seems unlikely that we'd identify one using these words, but in other domains, they may end up conflicting with another resource. Whatever you end up doing about that, it'll surely be gross.
I think plurals are better so nyah! Heh.
Also, it's totally my job to get hung up on these kinds of details. Clarity, avoiding collisions, enabling easy expansion, and especially averting future breaking changes to deal with the aforementioned matter to others.
API endpoints are not variables. Variable names are local and disposable, they don't even survive the compilation process in most languages.
Meanwhile, APIs, as interfaces, are forever. And the dumbest thing to do is to decide to have two names for one type in an interface, because grammar happens to have single and plural version for words. Why would you do that? APIs have no grammar, they're not sentences, they're made of identifiers that need to uniquely identify something. So stop trying to force grammar in.
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.
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.
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.
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.
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.
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.
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:
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?
Also, you should avoid verbs in URLs (IMHO, of course). You're adding to the students collection, so post to students: