The Elements of APIs (2021)
johnholdun.com
johnholdun.com
When championing good practices like these within a team, they are often somehow challenged, and "do it because I say so" is a weak answer.
Also, not understanding why these are good practices is a good way to end up doing cargo cult architecture.
Edit:
> Some of the choices I’ve listed so far may seem arbitrary, and they are! You and your team should make aesthetic changes if you want to, but I urge you to define them on a system level. If you can’t agree on something that is subjective, I recommend that you just do what I said, because it doesn’t matter and this way of doing things is already written down.
That's a very good point.
His advice here is spot on. You can’t underestimate how inconsistent the API landscape is, and he’s right that the fancier ones are harder to use.
Some notes:
- Surprisingly less than 5% of APIs reliably use PATCH.
- I’m not sure it’s a good idea to return an Object under data for single resources, and an array when requesting multiple resources. Theoretically it sounds better, but in the end it makes it harder to consume.
When I started building my companies main api about 8 or 9 years ago, PATCH was nowhere to be seen. The advice was PUT for creating and POST for updating. some resources had it the other way around, but it was always PUT and POST. I am surprised to see PUT has now been deprecated in favour of PATCH, but I fear that making a new version of the api just to swap 2 methods is unecessary.
A common difference between POST and PUT is that POST is often used for non-idempotent actions (creating a resource), and PUT for idempotent actions (updating or upserting a resource). Of course this is also purely convention; nothing in the implementation of either enforces that usage
Wait, what? Is that an "official" thing anywhere in regards to the method itself, or just an observation with the APIs that you've worked on?
One thing though: I rarely see PATCH and that's because clients might send "identical data" as POST multiple times. You have to know what they want to do in business logic anyway and clients need to understand your response.
Sure you can give them "409" or "303" back, but who expects those? Which one do you choose? You have to document it anyway? Or do you return 400 { error: "Already exists" }?
This isn't well defined in the HTML spec so implementing PATCH feels useless. It's easier to accept that you'll receive invalid data on POST and you'll have to return custom error codes.
Surely that should be "PUT for creating, POST for updating"? PUT is a standard verb, defined in every version of the HTTP/1.1 spec starting since RFC 2616, after all, unlike PATCH which is still just a "proposed" standard.
14 years on, I wonder what the hold up is.
I might perhaps consider adding “it’s secure" to that list...
(And if I might do some shameless self-promotion: https://www.manning.com/books/api-security-in-action)
[1]: https://google.aip.dev/121
[2]: https://google.aip.dev/160
> Your GETs support a filter query parameter, which works for every attribute of the resource being retrieved.
That's not easy in practice. You'd have to filter the entire collection on the server or database. For large tables, you'd need to index attributes and build the appropriate predicate, which can be challenging for normalized tables.
Enabled vs. disabled. There doesn't seem to be any priority given to communicating to the API client what parts are enabled or disabled at any given point in time.
Why?
I'd speculate about a little dog, but that'd be "Toto."
I plan to eventually incorporate guidelines on writing good openapi specifications, and general design patterns for API.
Very much agree with most of the points in the article, such as returning objects over flat array's, supporting partial updates via PATCH.
I'm less convinced by exclusion of PUT (sometimes a client generated id / idempotent create is useful), and ability to filter collections on all fields (sounds inefficient).
Look forward to returning to this when some of the to-dos have been filled out
As volumes increase the overhead of single document updates in the backend systems+database slows things down. Multiple connections can help but frequently there is throttling in the destination system.
It was only after I left Rails land that I discovered that these great patterns were not used everywhere.
I quickly returned to Rails.
> When I say “REST,” I don’t mean when to use GET vs. POST (although that’s also important). What I mean is that you should read Roy Fielding’s dissertation, Architectural Styles and the Design of Network-based Software Architectures, where Representational State Transfer was coined. Not once in its definition does he mention HTTP verbs!
Something that I still don't understand, is how HATEOAS relates to OpenAPI spec. Quoting Roy T. Fielding himself (https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...):
> API designers, please note the following rules before calling your creation a REST API:
> [...]
> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].
> [...]
> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
Wouldn't that mean that using OpenAPI spec automatically means something is not a REST API, but instead it's just an RPC?
Not saying that's good or bad, just contrasting this with OP's recommendation against using "an RPC-based interface" while also quoting Roy on REST.
(Edit: Added more context.)