How to Design Better APIs

It might be to formal for your use-case, but there is a standard defined for error responses in RFC 7807:

https://datatracker.ietf.org/doc/html/rfc7807

Localization has entered the chat.

You need codes because the field isn't going to be 'email' for much longer than it takes for your management to realize that people outside of the US also have wallets.

Such simple approach is limited only to errors without arguments.

For more complex use cases, where we would want an error message to indicate that field value was too long and in addition provide maximum field length, we would need to introduce new field in the error response.

While it is solvable by adding this information to client application side. It would create a situation where the logic is duplicated in two places (backend and client application)...

Also if we would want better UX, then we would need to display all errors at the same time in the form that is incorrectly filled. This would require changing error structure to return array of errors and it potentially create a breaking change in the API or would result in confusing structure that supports both, legacy and new format...

Some years ago, I wrote an article sharing the ideas on how REST API error structuring could be done depending on the complexity of application or service: https://link.medium.com/ObW78jhDkob

Agreed. But rather than reinvent, let’s just use JSON API standard?

https://jsonapi.org/format/

(Scroll to the very bottom)

It also doesn't hurt to repeat the HTTP status code in the JSON body - when you receive a response, the status code and entity body are coupled but even if the server logs the status code, they're often decoupled in the logging system - having both in one log entry is way easier!

Hey thanks for your input. These are great additions!

We do, it's called JSON-RPC.

I don't think I've ever come across any third party actually implementing HATEOAS (https://en.wikipedia.org/wiki/HATEOAS)

As someone who has spent a decade working with APIs, I 100% agree. The use cases that are a good fit for “RESTful” APIs pale in comparison to those that would benefit from RPC.

What is the point of having your client translate an action to some operation on a document (read or write), only to then have your server try to infer what action was intended by said document operation.

It pains me that this article doesn’t mention any of the trade offs of each suggestion (POST vs PUT vs PATCH and expandable objects, especially) or of using REST APIs generally.

So the problem with “Data transfer is in binary” is that it really requires both the source and the recipients to be running the same executable, otherwise you run into some really weird problems. If you just embrace parsing you of course don't have those problems, but that's what you are saying not to do... Another great idea is for a binary blob to begin with the program necessary to interrogate it and get your values out, this has existed on CDs and DVDs and floppies and tape forever but the problem is that those media have a separate chain of trust, the internet does not, so webassembly (plus, say, a distributed hash table) really has a chance to shine here, as the language which allows the web to do this quickly and safely. But it hasn't been mature.

The basic reason you need binary identicality is the problem that a parser gives you an error state, by foregoing a parser you lose the ability to detect errors. And like you think you have the ability to detect those errors because you both depend on a shared library or something, and then you get hit by it anyway because you both depend on different versions of that shared library to interpret the thing. So you implement a version string or something, and that turns out to not play well with rollbacks, so the first time you roll back everything breaks... You finally solve this problem, then someone finds a way to route a Foo object to the Bar service via the Baz service, which (because Baz doesn't parse it) downgrades the version number but does not change the rest of the blob, due to library mismatches... Turns out when they do this they can get RCE in Bar service. There's just a lot of side cases. If you're not a fan of Whack-a-Mole it becomes easier to bundle all your services into one binary plus a flag, “I should operate as a Bar service,” to solve these problems once and for all.

gRPC is encoding agnostic, and requires _no_ Protobuf at all.

See: https://grpc.io/blog/grpc-with-json/

Have you seen: https://github.com/twitchtv/twirp

While I totally agree with the overkill that REST can be, I really do NOT agree with your statement:

> but it requires another API specification

This implies API-specs are part of the problem; and I think they are not.

Specs that have generators for client-libs (and sometimes even sever-stubs) are verrrrry important. They allow us to get some form of type-safety over the API barrier which greatly reduces bugs.

One big reason for me to go with REST is OpenAPIv3: it allows me to completely spec my API and generate clients-libs for sooo many languages, and server-stub for sooo many BE frameworks. This, to me, may weight up to the downsides of REST.

GraphQL is also picking up steam and has these generators.

JSON-RPC (while great in terms of less-overkill-than-REST) does not have so much of this.

Agreed 100%. Slapping a REST api over a software is like reducing that software to a set of resources and attribute updates over those resources. And that never feels like the right way to talk with a software. That could be convenient for the majority of crud apps out there, but not everything we build is a crud system. For example how would you design operations on a cloud word processor as REST apis?

A better perspective would be, most softwares can be viewed as a set of domain specific objects and the set of operations (verbs) that can happen to those objects. These operations may not be a single attribute update, but a more complex dynamic set of updates over a variety of business objects. If you try to model this with a REST api, it either quickly becomes chatty or you end up compromising on REST principles.

GraphQL seems to make much more sense than REST, IMO.

I’m not sure what issue the verbs are creating, can someone help me get through my thick skull what this persons issue with them is? I don’t see how they add much complexity, just check the API docs and see what verb you need to use to perform a certain action.

>Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server.

https://github.com/asad-awadia/indie-rpc

I feel like the whole of the 1990s was devoted to this. How to serialize an object and then what network protocol should be used? But increasingly over time, between 2000 to 2005, developers found it was easier to simply tunnel over port 80/443. In 2006 Pete Lacey wrote a satire about SOAP, which is funny but also accurate, and look at how late people are to discover that you can tunnel over HTTP:

http://harmful.cat-v.org/software/xml/soap/simple

I was puzzled, at the time, why the industry was cluttering HTTP in this way. Why not establish a clean protocol for this?

But people kept getting distracted by something that seemed like maybe it would solve the problem.

Dave Winer used to be a very big deal, having created crucial technologies for Apple back in the 1980s and 1990s, and he was initially horrified by JSON. This post is somewhat infamous:

http://scripting.com/2006/12/20.html#godBlessTheReinventers

"... and damn, IT'S NOT EVEN XML!"

He was very angry that anyone would try to introduce a new serialization language, other than XML.

My point is, the need for a clear a clean RPG protocol, but the industry has failed, again and again, to figure out how to do this. Over and over again, when the industry gets serious about it, they come up with something too complex and too burdensome.

Partly, the goal was often too ambitious. In particular, the idea of having a universal process for serializing an object, and then deserializing it in any language, so you can serialize an object in C# and then deserialize it in Java and the whole process is invisible to you because it happens automatically -- this turned out to be beyond the ability of the tech industry, partly because the major tech players didn't want to cooperate, but also because it is a very difficult problem.

My current company has settled on "We use GET to retrieve data from the server and POST to send data to the server, nothing else" because it was causing quite a lot of bikeshedding style discussions where people were fussing over "Should this be a post, put or patch"?

It all came to a head when someone wrote an endpoint using a PATCH verb that some people were adamant should have been a PUT.

It was among the most silly nonsense I have ever been a part of and these discussions have thankfully gone to zero since we decided on only GET and POST

I agree entirely. I think https://github.com/webrpc/webrpc looks promising.

Dear PAM69, this is great advice if you want to end up with a slow-to-load, low-performing web application that your customers complain about and hate using. But at least it'll adhere to a specific notion of architectural "purity", right? /s

Anytime clients need to make 15 async calls before the UI can be displayed, you're headed up the creek. Generally speaking, this is an anti-pattern. There are exceptions, but they're not the rule.

It's better to weigh the tradeoffs in any given situation and make a decision about bundling sub-resource references based on what you're optimizing for.

A few quick examples:

* Dev speed: Unbundled

* Quick-loading UI: Bundled

* Sub-resources are computationally-expensive to query? Unbundled

This has been my experience consistently throughout 20 years of web-tier development.

I've consumed the kinds of APIs you're referencing and they are my least favorite. I would prefer a poorly documented API over one that returns me 15 IDs that I must look up in separate calls. I think there's a reason those APIs also tend to have rate limits that are way too low to be useful.

That's not a rest-y API.

You want

GET /orders?user=Id

Orders can be searched on many dimensions, not inherent to users

> you will find that the interface will become increasingly muddled.

Will I? For example The Stripe API uses expand parameters and I prefer that approach to "atomic" REST or being forced to use GraphQL. There is a missed standardization opportunity for incremental graph APIs built on REST.

> to obtain the "orders", the /users/:id/orders endpoint should be called

Ok, but an order has an array of order lines, and each order line has sub-arrays as well, like details of the packages it was shipped in etc.

So that might be 5-10 calls to get an order line, and for a few thousand lines we're looking at several tens of thousand calls to get a full order.

Secondly, you then make some changes and want to replace the order with the data you got. You then have to produce a delta and upload that. And those thousands of calls better be done in a transaction of sorts, otherwise you'll have big issues.

Seems easier to me to just be able to GET or PUT an entire order with all the details in one go.

Once your api query parameters reach a certain level of complexity, like such nested lookups, one should just consider giving direct proxied read access to the DB for clients that need it. Why reinvent your own query language. I Don’t know enough about graphql to compare it. Databases have access controls also.

Another two reasons to avoid nested resources, are performance and coupling.

A nested resource is hard to optimize. Simple, atomic, flat resources can be cached (by clients, proxies or server) much more efficient. Once you allow nested resources, there's no going back, as clients will depend on them. So you've effectively disabled lots of performance improvement options.

A nested resource implies data relations. Tightly coupled to a data model. One that will change over time, yet the api is hard to change. If you have a Project nested in your Users, and the business now needs multiple projects per user, this is hard to change with nested resources, but much easier with endpoints, the /users/:id/project can be kept and return e.g. the first project, next to a new /users/:id/projects.

I upvoted because I'm curious to hear what others are doing. We typically make sure to only make such breaking changes where either the now-required value or a sane filler value could be used. If it's the same API for the same purpose, it's usually not a stretch to assume the values for a new field are derived from some combination of an old field or else are primitive components of an old field such that they can be deduced and stubbed in your transition layer (or calculated/looked-up/whatever one-by-one as part of a bulk migration script during the transition). If your v2 is so drastic of a breaking upgrade that it bears no relationship to v1, I imagine your SOL and probably should have thought out your v1 or your v1-to-v2 story better, if only for the sake of the poor devs using your API (and you probably need separate tables at that point).

For other fields like your example of `avatar_url` I would use a placeholder avatar for all legacy users (the grey anonymous snowman profile comes to mind).

Those are possible, but ugly solutions. Two cleaner ones are either depracate and remove the v1 api altogether, or when inserting a record to the database from the v1 api, use a default dummy value for avatar_url.

We’re using event sourcing so the “projection” (db snapshot) have 2 different tables for v1 and v2. Think users_v1, users_v2.

Obviously there will be always challenges with eventually consistency but that is another topic altogether.

Have a default value for v1. Don't maintain two DBs just for this.

I really like this way of versioning https://medium.com/@XenoSnowFox/youre-thinking-about-api-ver...

It uses Accept and Content-Type to version resources: application/vnd.company.article-v1+json

I'm not saying you should do it this way, this is just how our startup (still very much in the "move fast and discover product fit" stage) does it. We have separate API models (pydantic and fastapi) and DB models (sqlalchemy). Basically everything not in the original db schema ends up nullable when we first add a field. The API model handles validation.

Then if we absolutely do need a field non-null in the db, we run a backfill with either derived or dummy data. Then we can make the column non-null.

We use alembic to manage migration versions.

But we aren't even out of v0 endpoint and our stack is small enough that we have a lot of wiggle room. No idea how scalable this approach is.

The downside is maintaining separate api and db models, but the upside is decoupling things that really aren't the same. We tried an ORM which has a single model for both (Ormar) and it just wasn't mature, but also explicit conversions from wire format to db format are nice.

b -> What happens if the "list of IDs" is 10k or 100k or 1M+?

> Pagination is the devil. The state of the server can change while the user is paginating, leading to fragile clients. Don't paginate your API.

The problem is not pagination, and the solution is not to avoid pagination. The problem is offset-based pagination, and the solution is to use cursor-based pagination.

> If you think you have a need to paginate, have one API call return a list of IDs, and have a separate API call return a list of resources for a given list of IDs, where the second API call accepts some maximum number of IDs as a query parameter.

This has the same problem as you described above. The state of the server can change between fetching the list of IDs and operating on them.

Pagination by offset can be bad. Pagination by cursor which is specifically designed for your list of resources is perfectly reasonable. Use stable pagination queries, not ?*

Pagination is harder than it seems to get right.

I think pagination is only predictable under these conditions:

1) The offset used for the next fetch must be based on a pointer to a unique key. We can't rely on the number of rows previously seen.

With this rule, deletes which occur to rows in previous pages will not cause unpredictable contractions.

2) The paged result set must be sorted based on a monotonically increasing field, like created_at, plus enough other fields to create a unique key. You could lean on the PK for this, i.e.: ORDER BY (created_at, id) ASC.

With this rule, new inserts which occur during page enumeration will only affect unseen pages (and we'll see them eventually)

The API call looks roughly like this:

  /orders/?region=US&offset=(2022-03-12T07:05:58Z&ord_1234)&limit=100

The DB query looks roughly like this:

  SELECT *
  FROM orders
  WHERE (created_at, id) > (:offset_created_at, :offset_id)
  OR (
    :offset_created_at IS NULL 
    AND :offset_id IS NULL
  )
  ORDER BY (created_at, id) ASC
  LIMIT :page_size

EDIT: formatting

Any pagination is brittle. Regardless of whether its by page, cursor or something else. You can't have equal sized pages if there is a risk that there are deletions on a previous page or at the exact index you use as a cursor etc.

The solution is usually simple: assume it doesn't matter. Write a spec for your feature and explicitly state that "In the solution we assume it doesn't matter if the same record is ocassionally reported twice or a record is missing from the pagination in some cases". Done.

Are you able to elaborate on what is a response envelope?

Edit:

Nevermind, see [0]. It's the simple and intuitive concept of encasing the payload in an consistently structured object which includes metadata, e.g.

    {"Error": null, Data: ...}

[0] https://stackoverflow.com/questions/9989135/when-in-my-rest-...

Makes intuitive sense, as it's then easier to develop a nice, generic REST client.

- Always use a response envelope

I would mostly agree except in 1 case, streaming data is easier without an envelope. Making some array inside an envelope stream is usually more code and messier than just getting some metadata out of header. So if you have something like data integration endpoints and you expect someone could pull many megs of records, consider no envelope.

AIPs are very deep and comprehensive, I would say "similar" is a diplomatic understatement here :)

Author here. I generally agree - IF something goes terribly wrong within the application, a 500 is definitely the way to go. The thing is - these just shouldn't happen that often. Because in that case we're having a bigger problem. :D For example I have never seen Stripe return a HTTP 500 from their API. Thing just works.

> I tend to follow the patterns [...]

Can you elaborate on this? Give examples?

Agree that the tendency exists but don't see the tradeoff between transactional and messy in this example--you should be able to create a new product with options [...] in the same request, perhaps using /options to ascertain what's available before posting to /products, depending on the situation.

Generally internal APIs are developed alongside one or two apps. They don't need a pure, resource-oriented, API that perfectly represents the domain models but ignores how the API is used in practice.

A good example is the tip on PUT vs PATCH to update objects. That seems to be missing the point. Why are you forcing the clients to calculate the correct resource fields to PATCH to the server? This is supposed to be an API, not a database. Just expose methods that correspond to the actions that the users will perform.

Sure, HTTP only has 5 verbs, but that doesn't mean your API should solely consist of five possible interactions on a resource.

i was in the process of writing a snarky reply describing how the next level enterprise approach is to host api/product in microservice A and api/options in microservice B, each with their own internal data store using completely different tech stacks.

but, if you've already suffered through the pain of attempting to implement some kind of best-effort ad-hoc distributed commit logic in your client code, then needing to call two completely different services for api/product and api/options doesn't really make anything _worse_.

on another hand, it doesn't make anything better.

Everyone has different experiences but my view of the problem is that it's not so much down to developer laziness as it is technological ignorance and reactive direction from higher up - the people who actually fund and approve the work.

Outside of the bigger providers I don't think most APIs are designed with general consumption in mind. The impetus usually seems to be reactive - "we've got this idea for a mobile app using data from our legacy WMS/CRM/whatever, and it needs to be finished yesterday!"

So generally (not always but usually) what I've seen is whatever the underlying system supports and requires gets reflected into the API, and there's minimal proper engineering or sensible abstraction, partly because of time limits and also because the requirements are discovered mid-flight.

"Oh... Products have options in a separate entity? Oops. Uh, we'll add an options endpoint. Easy."

Several years later, the app is mildly successful, the business decides to whitelabel the API for some of their B2B clients, there's no budget for a redesign, "It works doesn't it? If it ain't broke don't fix it..."

Where possible I try to design and build APIs with some forethought and push for as much information on requirements and capabilities of existing systems beforehand but quite often the stakeholders don't really know and don't want to pay for a few weeks of in-depth analysis.

The endless facepalming of hearing the cycle of "Don't overengineer it" when I ask too many questions people can't answer, through to "Why didn't we pick up on this requirement" and having to listen to "we can all learn from this" when something fails because of some if/else statement buried in the legacy business logic, right back to "Don't overengineer it" when you propose the clean way of encapsulating that in the API, has left a permanent indent on my skull. So much leakage of black-box logic into the clients which bloats frontend logic and provides plenty of double handling and scope for unknown business logic to be missed, and no one in charge really gives a shit other than the developers and engineers, and that's fine because we can deal with it and it's their fault for not thinking of it anyway... they're the smart ones right?

You'd think this is just a problem with SMEs but some of the biggest national and multinationals I've worked with have a ton of horrid shit in their API designs. One industry-wide government-mandated reporting spec you'd post a SOAP envelope that wraps an undocumented XML document (they had an example document and the envelope was documented, but no doctype or anything to go off for the contents), a major real estate interchange format has you polling a REST API for an update flag, then loading and saving CSVs over FTP. Some godawful affiliate marketing API essentially just exposed their nth normal form relational database as an API. One government department just used HTSQL for their API using a python script to reflect some of their silos into PGSQL and called it a day (even though whether or not your interactions would work or made sense depended entirely on their internal application logic which wasn't represented or documented).

And too many projects where it turns out the promised APIs didn't even exist until the app was well into development. "Don't worry about it, that's their problem and gives us an excuse when the inevitable delays occur..."

No wonder we're hearing of massive breaches daily, from top to bottom the entire industry is barely held together by glue and sticky tape. It seems like an engineering problem but I think it goes much higher than that, it's a cross-industry failure in planning and management. Engineers are not given the time and budget to do the job that the data deserves. The market self corrects though, massive breaches have closed more than one business down for good.

It feels futile but I do support and encourage people to work towards just reasonable and well-documented endpoints, I doubt there's one true standard, but just some level above slapping it together at the last minute would be nice. I don't care if it's JSON or XML, or whether paths follow some semantics or another. As long as the relationships, types, and mandatory vs optional fields are explained clearly and succinctly, and the auth mechanism isn't a nightmare, and I can work with it.

Sorry for the rant this is just one area that triggers me. I've seen too much bad practice, and fighting against it for decades and still hearing the same lack of concern in the architecture phase has left me more than a little jaded.

If options are children of products and not many-to-many then the only logical way to have two endpoints in the API is if the parent (Aggregate root in DDD speak) items are readable/writable as a consistent tree, while the query for child items in /api/options is a read only api.

There is nothing nonstandard about such a REST api. If a product must be associated with an option then the /product/create endpoint should only accept a product with an option already attached.

> This kind of “pure” rest api is simply convenient to the developer because they push the problem of object consistency to the client.

It's not like REST means that to be "pure" or "standard" you end up exposing all your database tables with read/write and just let callers CRUD anything they want, including creating inconsistent data?

> “the rules” of rest APIs.

The rules are very simple: the REST api should expose and enforce the consistency rules of the business logic!

> it is impossible for a client to perform an atomic operation on multiple distinct objects types.

> It doesn’t meet the “standard” for a rest api? Too bad.

It is perfectly fine to model the creation of a product with options via a new resource. Another possibility is to model this as a transaction, a series of requests. Both meet the goals of atomicity and also following restful constraints.

But since you disallowed those possibilities as the premise, there is no constructive way forward from there. Nice construction of a straw-man, must feel satisfying to see it topple over, but who do you hope to impress with that?

My own experience is that (unix) timestamps are much less error-prone than textual representations like ISO 8601 and such. A field like `update_time_seconds` is clear and easy to convert into any representation. This is what the Google API Improvement Proposals recommends in most cases, though civil timestamps are also described. https://google.aip.dev/142

Of course, when preparing queries against the API, you may need a helper to build valid timestamps. But this is mostly relevant to the discovery phase which isn't automated. And textual dates also have drawbacks, for instance the need to encode it when used a an URL parameter.

Why use string-based timestamps at all? Use unixtime. It's much easier to parse and it literally can't be malformed.

Author here. Thanks for the nice words - I appreciate it. I've read that a couple of times in the comments already. Definitely something worth considering, Stripe does this as well. Thanks for your comment.

Authentication and Authorization are two subtly different things. In this case, you may want an API key (Authentication) to be required to ensure things like rate limiting is enforced, but then want proof that the call is operating on a user, or is a machine-to-machine interaction which OAuth2 Bearer tokens work nicely for (Authorization)

Both

  /books
  /book/:id

  /clothes/:clothing_id

The reason for using plural is because without the `:clothing_id`, `/clothes` endpoint would return a collection of clothing.

I always prefer singular just because it's easier to spell if you know the type.

It's stupid to have /geese return a Goose.

If the APIs were in Esperanto it would be different.

We use the form that represents a collection of objects. For example books and clothing both refer to a collection of things so I take them as valid forms

Ah yes, the classic:

POST /document/:id?params

Creates a document with parameters

Based on that description, you may be using PUT in conflict with its semantics (namely, idempotent way to replace an entire resource).

This is one reason why I don't bother with these methods and stick to GET and POST.

I would go with POST with a body in that case, where I interpret is as a "new search item" and use GET to scan through results, if there are many results available. I don't think I've needed something like this more than once or twice though. From users perspective, asking information on specific 50 items at once is not something commonly done.

There was a new RFC published a few months ago to address this use case. It defines a new HTTP method QUERY, which is defined to be safe & idempotent like GET and explicitly allows a request body like POST. See https://www.ietf.org/id/draft-ietf-httpbis-safe-method-w-bod...

The type signature:

` list of uuids -> list of results `

is usually bad design to begin with.

If QUERY is too new, I was always a fan of base62 for URLs, but base64 and straight binary encoding could do well for compacting UUID lists, they are essentially just giant verbosely written integers.

Human readability most likely

They can include a local timezone. Sometimes there's a big difference between 12am in UTC+0 and 3am in UTC+3 despite representing the same instant in time.

1. Human readability

2. The ISO date format is "big endian" by default, which makes it trivial to chunk and compare just specific date parts. Want all events that occurred on the same (UTC) date? Just do dateField.substring(0, 10). Everything in the same year? dateField.substring(0, 4).

I prefer them because they're human readable and can preserve time zones if that's important

8601 has a large pattern space - RFC 3339 is a narrower subset of ISO. Somewhere I saw a diagram that convinced me. I link if I can find again.

Edit: a relevant link

https://news.ycombinator.com/item?id=28976526

* Human readable

* Supports birthdays for people older than 52

* Reliable after 2038

* Supports leap seconds

* HTML date/time spec is a subset

* String collation order matches temporal order

* Excel

What are the use cases where idempotency is not needed or even harmful?

I don't think we should strive to remove non-idempotent cases. If something is not idempotent does not mean it is bad. It just means that request should be handled differently.

In your example (and I ask this as I remained confused after also reading SO):

Let's say that you need the client to provide the ID in the request body.

In this case, how is using PUT when creating a new resource idempotent if the ID should be unique and you have a constraint on the DB level for example?

What happens when the second call will be made with the same ID?

If I execute the following sequence:

Call 1: PUT resource + request.body {id: 1} => a new record is created so the state of the system changes

Call 2: PUT resource + request.body {id: 1} => no record is created, maybe the existing one is updated

IMO this is not idempotent nor should it be. Creating a new resource is not an idempotent operation.

I also don't like that depending on the state of the DB two requests with the same attributes will have different impacts on the system.

In my mind as a consumer of an API it is simpler: POST it creates a new record so I know what to expect, PUT updates an existing one.

Author here. I read that a couple of times already. RFC 3339 is what you should use - I should probably change that (it's what I actually meant). :) Thanks for pointing that out.

Thanks for the kind words! Appreciate you reading it.

Even beyond PUT vs PATCH I found this statement to be rather naive:

"From my experience, there barely exist any use cases in practice where a full update on a resource would make sense"

Just in finance I can think of *dozens* of use cases around invoicing and purchasing *alone*. A lot of times thousands of resources may need just one field "corrected", but hundreds others "reset" to ensure the proper retriggering of routing, workflows, and allocations. That the resources need to exist as originals is incredibly important for these kinds of things.

Side note: I find it quite annoying that web devs have hijacked the term “API“ as a synonyme for “web API“, to the point where many devs are not even aware of the original broader meaning.

Nevertheless, as a (largely) non-web dev I found the article interesting and useful.

Author here. Haha! You are right. I admire Stripe's API and there's absolutely a lot of things in it that are my "benchmark" when it comes to good APIs. However, they return UNIX timestamps, for example, which I don't like that much (as stated in the post). They also use POST for updates, because, if I recall correctly, PUT/PATCH wasn't a thing yet when Stripe was built initially. Thanks for the comment.

What is the reason?

Are you saying dump DELETE because you should instead logically delete it with an IsDeleted column passed in via POST?

Huh? There’s full browser support for all of those verbs.

What is the argument for not supporting them?