Hacker News Reader

Comment by elevation | Hacker News Reader

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.

View on HN

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

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:

    GET /classes/{class_id}/students

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?

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

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.

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.

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

In HTML, you could have a FORM with the URL of /lamp/switch that you PUT.

So you're putting a switch. Great API design.

PUT is not a valid method from an HTML form. Only GET or POST are permitted.

This kind of reveals a little secret of many of the REST gurus. They have no clue what they're talking about.

> one of Fielding's own examples from his blog

Where?

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.

If I use turning a lamp on and off, I'd do GET /lamp and in the response there should be an href with a rel of "on" that I can follow (in JSON land).

In HTML, I might have a FORM that does a POST of the lamp's switch to /lamp/switch.

Because the switch is the resource that you're trying to manipulate when turning a lamp on/off, not the lamp itself.

POST /lamp/switch is not any better than POST /lamp as neither communicates what you're doing.

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

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.

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.

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

ie:

GET /species

and

GET /species_list

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.

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.

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

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?

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

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

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

Reply on news.ycombinator.com