3 ms·
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 o
by 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 agoIn HTML, you could have a FORM with the URL of /lamp/switch that you PUT.
- 3cats-in-a-coat 3y agoSo you're putting a switch. Great API design.
- cxr 3y agoPUT is not a valid method from an HTML form. Only GET or POST are permitted.
- 3cats-in-a-coat 3y agoThis kind of reveals a little secret of many of the REST gurus. They have no clue what they're talking about.
- cxr 3y ago> one of Fielding's own examples from his blog Where?
- Clamchop 3y agoI 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.
- 3cats-in-a-coat 3y agoAPI 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.
- rswail 3y agoIf 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.
- 3cats-in-a-coat 3y agoPOST /lamp/switch is not any better than POST /lamp as neither communicates what you're doing.