[HN Gopher] The Elements of APIs (2021)
___________________________________________________________________
The Elements of APIs (2021)
Author : luu
Score : 127 points
Date : 2024-09-03 07:04 UTC (2 days ago)
(HTM) web link (johnholdun.com)
(TXT) w3m dump (johnholdun.com)
| artpar wrote:
| If you like JSONAPI I maintain a 100% JSONAPI compliant headless
| cms
|
| https://github.com/daptin/daptin
| knallfrosch wrote:
| 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.
|
| 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.
| tlarkworthy wrote:
| GET and (sparse upserting) PATCH is all you need for a
| multiplayer API. Arguably GET is spurious as you could do an
| empty PATCH to do a read but you generally want a cache infront
| of GET that exploits etags
| Joker_vD wrote:
| What format do you provide for in your Accept-Patch header
| that accepts empty inputs?
| nmadden wrote:
| > Here are my priorities, in order of importance. I think these
| should be your priorities too.
|
| 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)
| halayli wrote:
| IMO the book title be 'The Elements of Web APIs'
| layer8 wrote:
| Note that this is about web APIs specifically.
| frabjoused wrote:
| 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.
|
| 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.
| fabianholzer wrote:
| I would wrap a collection always into an object, makes evolving
| the api in a backward compatible way easier. I am still
| maintaining a few endpoint where I choose differently, and have
| cursed younger me more than once for it.
| alt227 wrote:
| > Surprisingly less than 5% of APIs reliably use PATCH.
|
| 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.
| n_plus_1_acc wrote:
| I've seen both PIT and PATCH used side-by-side, where put is
| a complete replacement and patch is where to, well, patch
| only what you need, sometimes using the JSON-patch format.
| LargeWu wrote:
| The difference between PUT and PATCH, at least in convention,
| is that PUT tends to assume you are providing the entire
| object of whatever it is you're updating, and PATCH will
| accept a partial object and combine it with whatever's
| already there.
|
| 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
| Joker_vD wrote:
| > You use GET for retrieving, POST for creating, PATCH for
| updating, and DELETE for deleting.
|
| 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.
| Mainsail wrote:
| For reference, the author touched on their reasoning at the
| bottom of "Many nouns, few verbs"
|
| https://johnholdun.com/apis/verbs/
| lelandfe wrote:
| Huh, TIL that PATCH isn't an accepted standard:
| https://www.rfc-editor.org/info/rfc5789
|
| 14 years on, I wonder what the hold up is.
| sdeframond wrote:
| While I enjoy this kind of resource, I miss some explanation
| about _why_ they recommend doing things that way.
|
| 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.
| kaeruct wrote:
| 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...
| bobbiechen wrote:
| It is a convention from journalism that is similar to TODO:
| https://en.wikipedia.org/wiki/To_come_(publishing)
| Mainsail wrote:
| 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?
| mnahkies wrote:
| In terms of taking an openapi specification first, then
| generate server/client from that approach, I have a project
| that focuses on this for nodejs koa and fetch/axios:
| https://openapi-code-generator.nahkies.co.nz/overview/about
|
| 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
| pqdbr wrote:
| Having learnt web development by coding Ruby on Rails, I wouldn't
| design an API any other way.
|
| It was only after I left Rails land that I discovered that these
| great patterns were not used everywhere.
|
| I quickly returned to Rails.
| sa46 wrote:
| 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.
|
| [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.
___________________________________________________________________
(page generated 2024-09-05 23:01 UTC)