APIs are simple, small and approachable – Why do they require an API Architecture?

It is very hard to move the pillar of a bridge, which is made of steel and concrete. Such changes are difficult, costly and time intensive. This is why a blueprint is created before building the bridge. It allows planning all the details in advance, iterating over several proposals and performing what-if analysis. Changes to the plan are easy and cheap to perform. And by making changes to the plan, it hopefully becomes unnecessary to make changes to the real artifacts. The same is true for APIs.

When APIs have already been built, changes are difficult, expensive and time-intensive. Even worse, the changes to published APIs might break any clients using the API. In consequence, the consumers might get upset and switch the API provider. To avoid this, the API needs to be right from the start, by the first time it is published.

This can be achieved by planning ahead with an API architecture. An appropriate API architecture increases the efficiency of building the right API, reduces the cost and time for both construction and maintenance and thus reduces technical risk associated with the construction. An API architecture is an approach for risk mitigation. It enforces that the approach is well thought out before construction is started. It avoids situations where resources are spent on implementing APIs, which cannot possibly fly.

An appropriate API architecture enables a contract-first design approach. Once the architecture is externalized and written down it can be used not only by the API providers to implement the API proxy, but also by API consumers to build apps with this API. The API consumer does not have to wait for the API to be finished, but development of API and app can proceed in parallel.

Non-functional properties of the API should not be an afterthought. The API needs to be designed right from the start to fulfill all non-functional properties such as security, performance, availability. Based on an architecture, the implications of the architectural choices on non-functional properties can be determined early in the design.

Proper architecture and design of the APIs is an investment. In the long run, it will save time and even help avoiding mistakes.

If you need to build APIs, you might be interested in my new book on API architecture and API methodology.

Why do we need an API Architecture?