Governing APIs after they Ship

Aidan Cunniffe 2023-04-04

API Days Paris December in '22

Last December I had the privilege of speaking at API Days in the beautiful city of Paris. My talk was titled "Governing APIs after they Ship". A lot of talks at API conferences cover the happy path -- a new project where we can spend the time to ship a well-designed API the first time. I wanted to do something different, I wanted to talk about the messy real-world many of us live in.

The full talk in 16 minutes and linked below, but here are some quick notes I took watching it again:

• APIs are not your code, it’s the promises you make to your consumers. You can’t keep your promises if you don’t know what they are. So the 1st step of governing any API is to get caught up. You need to take the time to figure out how your API works today -- those are the promises you have to keep. There are many tools like Optic that can help you quickly create an accurate OpenAPI spec.
• The next highest leverage thing you can do is start doing API Reviews whenever a change is proposed. Reading OpenAPI is hard for developers but there are great tools that can help
• Nobody wants to break the promises, but often it is very hard for a developer to figure out which changes are breaking. Adopt tooling to catch breaking changes in your pipelines so they get flagged early.