While I enjoy this kind of resource, I miss some explanation about <i>why</i> they recommend doing things that way.<p>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.<p>Also, not understanding <i>why</i> these are good practices is a good way to end up doing cargo cult architecture.<p>Edit:<p>> 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.<p>That's a very good point.
I founded an integration startup, so my entire life right now is figuring out how to connect to and normalize an endless number of APIs.<p>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.<p>Some notes:<p>- Surprisingly less than 5% of APIs reliably use PATCH.<p>- 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.
Pleasently surprised. I was taken aback when I read the "by John Holdun" line and suspected shameless self-promoting, but the site is really well written and structured.<p>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.<p>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" }?<p>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.
> You use GET for retrieving, POST for creating, PATCH for updating, and DELETE for deleting.<p>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.
> Here are my priorities, in order of importance. I think these should be your priorities too.<p>I might perhaps consider adding “it’s secure" to that list...<p>(And if I might do some shameless self-promotion: <a href="https://www.manning.com/books/api-security-in-action" rel="nofollow">https://www.manning.com/books/api-security-in-action</a>)
Contains similar advice to resource-oriented design and Google's API Improvement Proposals [1]. I've been pretty happy with resource-oriented design--makes for a very uniform API and avoids much of the bike-shedding over decisions like the filter [2] and pagination format.<p>[1]: <a href="https://google.aip.dev/121" rel="nofollow">https://google.aip.dev/121</a><p>[2]: <a href="https://google.aip.dev/160" rel="nofollow">https://google.aip.dev/160</a><p>> Your GETs support a filter query parameter, which works for every attribute of the resource being retrieved.<p>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.
You know what's not discussed here, or in pretty much any discussion of APIs that I can recall?<p>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.<p>Why?
I like it, but I wonder what TK means. It must be something like a todo, because it's always used to mark incomplete sections. And since the date says 2021, I'm also left wondering when an update could come...
This was a great read but one thing I'd like to see is some examples that, for the most part, follow these conventions. Any suggestions that I can dig through as a reference point?
Something not mentioned that I've run into frequently is the need for batched operations (i.e. not single document at a time posting).<p>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.
Having learnt web development by coding Ruby on Rails, I wouldn't design an API any other way.<p>It was only after I left Rails land that I discovered that these great patterns were not used everywhere.<p>I quickly returned to Rails.
Re: <a href="https://johnholdun.com/apis/rest/" rel="nofollow">https://johnholdun.com/apis/rest/</a><p>> 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!<p>Something that I still don't understand, is how HATEOAS relates to OpenAPI spec. Quoting Roy T. Fielding himself (<a href="https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven" rel="nofollow">https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...</a>):<p>> API designers, please note the following rules before calling your creation a REST API:<p>> [...]<p>> 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].<p>> [...]<p>> 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.]<p>Wouldn't that mean that using OpenAPI spec automatically means something is not a REST API, but instead it's just an RPC?<p>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.<p>(Edit: Added more context.)
If you like JSONAPI I maintain a 100% JSONAPI compliant headless cms<p><a href="https://github.com/daptin/daptin">https://github.com/daptin/daptin</a>