API is a language!

There are many different ways in which you can answer the seemingly simple question: “What is an API?”

Previous discussions focused on the technical fundamentals (“it has to be networked and reusable”) and on the bigger picture (“it’s a delivery mechanism for a product”).

Today, we’ll look at the functional essence of what an API is, how that essence comes into existence, and who it is for.

What is an API? It’s a language!

At a fundamental level, APIs can be compared to being languages: It’s a communications mechanism that allows applications to communicate.

Much of the value of APIs is based on this “language nature” of APIs: If the only thing that two applications need to collaborate is to agree on a language, then there is much more freedom for these components than in more tightly coupled scenarios, where agreement may also cover aspects of how applications are implemented, or where they are run.

It’s interesting to think about who is creating and using the “API language.” It is certainly used by communicating applications (like the weather API example shown in the video). But these applications are simply executing instructions that were created by developers:

• API developers design the API and therefore design the language (they have to choose an API style and then design the API for that style). They implement the API, and they publish the API to allow others to learn about the API and its language.
• Application developers discover the API and then can read the API documentation and learn about the API and its language. They then implement an application that uses the API and now the API consumer and the API provider can successfully communicate.

Important takeaway

The important takeaway from this is that the “API language” is designed by developers and consumed by developers. Applications then use the language to interact, but the act of understanding the API is done by humans on both the provider and the consumer side.

This shows that for APIs to be successful, they of course need to be functional so they can fulfill the role of allowing applications to communicate.

More importantly, APIs are a communications mechanism between developers, and therefore a limiting factor for API success is how well they work in this scenario.

This means the API itself must be well-designed, but it also clearly shows that additional factors such as documentation, examples, sandboxes, support channels, and similar supporting materials play a critical role as well.

All of this is often subsumed under the name of developer experience (DX), and it is something that often is overlooked (at least when the discussion is about private APIs and not about a partner or public APIs).

It is exactly this nature of the API as the way how developers communicate that allows APIs to scale so well.

If an API’s documentation is good enough for application developers to use it without ever having to talk directly to the API developers, then hundreds or thousands of application developers can use the API, without this scale of API consumption resulting in any bottlenecks.

If you want to learn more about this view of APIs as a language between developers, including a view of an example API and how this API plays the role of enabling developer communications, check out this video: