In API design (as in many things) it’s a good idea to keep a north star in mind – a few companies that do it better than everybody else, and whose conventions can be used as a baseboard the next time you build something greenfield.
For years, the go-to example of good API design has been Stripe, which along with a powerful API, is also well-known for being a major innovator with its API reference documentation and client libraries.
Stripe’s still good, but many other parties have been catching up. These days, for my money, one of the best example of good API design in the wild is OpenAI.
You’ll immediately notice similarities between OpenAI’s documentation and Stripe’s. OpenAI and Stripe have considerable interrelated history, and very likely that was a factor in OpenAI drawing influence from Stripe. This is a big part of what makes OpenAI’s API design good – it reuses many of Stripe’s conventions, but refines the faults in Stripe’s API that have gone unaddressed.
Notice these commonalities between the OpenAPI and Stripe APIs:
idfield. IDs get an object prefix to help disambiguate them. e.g.
file-123on OpenAI versus
typefield indicating their unique type name. e.g.
createdtimestamp. Not that unusual, but like Stripe this is a Unix epoch integer rather than RFC3339, the latter being the more common format choice these days.
/v1/in the path, largely an ornamental embellishment which like Stripe’s, isn’t likely to be incremented.
They’re subtle, but there are enough ways to design an API that these are clear signs of inspiration.
But OpenAI’s carefully chosen places to diverge from Stripe’s conventions to improve on them:
application/x-www-form-urlencoded. I’ll write more on this separately, but the latter, although human-convenient in some cases, was a major pain point within Stripe over the years.
Note that most of these improvements are related to API documentation rather than the API itself. This goes to show that as long an API has a decent baseline quality to it, it’s the documentation that’ll really make it shine.
OpenAI’s API quality is great, but not perfect. Some noteworthy blemishes:
created_atdepending on the object.
Still, nothing wildly terrible. Even with them OpenAI rests comfortably in the top few percent of well-designed web APIs.