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