An API is a promise

What is an API? This is an interesting question that can be answered on many levels. There certainly is a technical side to it, then there is the perspective of looking at it as a way to interact with valuable capabilities, and you can also think of it as a way how developers design and use languages for those interactions. But here, we take a fresh perspective and make the claim that an API is a promise. An API is a promise in the form of a team publishing a language (the API definition) that allows other teams to get something done (by writing code that uses that API). Other teams will use that language to build on top of it, and because of that, the promise must have a number of properties:

• It works. The API has a clearly stated purpose and value. By reading its definition and description, teams can understand it and start building on it.
• It keeps working. There will be code depending on the API, which means that it is important that the API keeps working as promised so that the code using it will keep working.
• It can improve. The promise can be evolved and improved by making it more elaborate, but you can never take away things that you have promised (and that consumers count on as a result).
• It doesn’t just stop. If you plan on not fulfilling your promise anymore, you have a way how to announce this and alert consumers, so that they can prepare for when the API stops working. This list of “how to manage your API promise” is (unsurprisingly) largely in line with good practices of API product management. One of the big value propositions of APIs is that by decoupling teams, you improve reusability, reuse, and velocity. The better your API promises are, the better this will work. Thinking about who is affected by your promises, it becomes evident that APIs span the whole range from being “just for machines”, but on the other side of the spectrum also being behind all of the digitally powered or enhanced experiences that users are expecting today. Let’s look at these layers of parties depending on API promises:
• Machines. Being relatively simple, machines will blindly execute the API promise that a developer turned into code, and they will stop working when the API breaks its promise.
• Developers. They are the ones understanding the promise and then turning it into code. Now your promise is engrained in a piece of technology that is potentially hard and expensive to change.
• Designers. They are the ones taking promises and building new ones on top of them, ultimately building new applications and experiences for users. If the building blocks they build on are breaking, their design breaks and they have to go back to the drawing board how to come up with a new one.
• Users. Delivering value to users is the ultimate goal of any API. Applications and experiences built on top of APIs will work more stable when API promises are being kept and can be more elaborate when designers can build on a solid foundation of building blocks. If you are interested in more details about this view of APIs as promises, the following video goes into more details. It is particularly interesting for everybody looking for an API perspective that goes beyond a pure technology focus and instead looks at why APIs are so essential for designing and delivering digital experiences today.