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

why do we need 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 the 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 the 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 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 to avoid 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?

Also published on Medium.

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.