A Comprehensive Guide of API-First Approach to Software Development
Tags: webdev, api
Published: 2022-10-12 14:35:29

The IT infrastructure has gone through rapid evolution and has even gone through several big revolutions since it stopped being the privilege of the military and scientists. 

Much of this happened thanks to business, which found many opportunities to realize its interests and gain profit there. However, the rapid growth in the number of services made the network infrastructure more complex, which required more and more financial and material resources to develop new services. 

Therefore, some companies decided to make it their business to solve the infrastructure problems. More specifically, they decided to make it their business to provide solutions that would greatly simplify the development of other services and their integration. That is what gave rise to API as a technology, and the different ways of developing and using it gave us such an approach as API-first development. 

So let's take a closer look at the API-first development and API first architecture. Let's also talk about API-first business value using concrete examples of companies which use API-first Development.

##What is an API Approach?

An API or Application Programming Interface is an additional software layer that unifies requests to the server side of service to provide simple, fast and reliable access to its functionality.

Accordingly, the API approach is a software development that puts APIs at the core of your service architecture and builds the necessary infrastructure around it, like integrations for other services and clients for different platforms. 

And there are two options here: either you already know what API as such and fully understand the meaning of the definition, or you don't. Then try to imagine the following situation. 

You flew on vacation to another country where everything is in a language you don't know. You need to explain to the chef what you want to eat when you go to a restaurant. But you do not know each other's language, and the chef is used to cooking specific dishes, not improvising. 

The waiter comes to the rescue, who learns about your taste preferences, and passes them on to the chef in a language understood by the chef and in the form of a specific dish. So, in this situation, you are on the client side, the chef is on the server side, and the waiter is the API.

Okay, you've got a pretty accurate definition and clear illustration. But to fully understand the API architecture itself and see the API business value, you need to dive quite a bit into the history of its emergence and development. Don't worry. We'll also accompany this with illustrations for those hearing about it for the first time.

###Client Server

Initially, we had a monolithic architecture, where client and server parts were common, queries to the service were made directly, and from it directly to the database. If we needed to integrate with third-party services, the corresponding functionality had to be integrated into the main architecture.

![No API](https://images.prismic.io/superpupertest/9caf49e2-3575-44a9-aec2-3c6ebf508053_API_3.png?auto=compress,format)

It was a working solution on which the whole early Internet successfully ran. But with client-side overload and a growing number of integrations, the solution became increasingly difficult and expensive to maintain and scale. 

If you continue with the previous illustration, it's more like a diner with a kitchen stove and a refrigerator right behind the bar. You come in the morning and tell the chef you want English breakfast. The chef takes ingredients from the refrigerator, cooks eggs and bacon right in front of you, and immediately puts the dish on the bar counter. 

###API

Then came the understanding of the urgency of the solution, which would be an interface between the server part, where all the logic of the service was happening, and everything else. But at that moment, the primary focus was on integration problems, and that's what the API was mostly introduced for.

![API](https://images.prismic.io/superpupertest/3563878e-3745-4d2a-bfc0-0e292806f252_API_4.png?auto=compress,format)

So, in the case of the client and server, the architecture remained monolithic, and requests continued to be made directly. But the integrations were already making requests to the database via API, which allowed you not to implement functionality for them in the common architecture. This reduced the complexity of the architecture many times and made it easier and faster to work with. 

For illustration, here, you can still communicate directly with the chef, but the waiter is already serving hot coffee in your cup and ready to offer you the dish of the day.

|**API advantages**|**API disadvantages**|
|-|:-:|
|Simple Integrations. Thanks to API, it's possible to provide access to your service much easier and faster.|Duplication of logic. Because the API had to repeat or follow the logic of your service in many ways, and over time, this turned into two parallel developing applications that sometimes started to go in different directions.|
|Lower component dependency. If the integration of a third-party service caused problems, it did not affect your service.|Shared database. If there were a problem in the database, both the API and your entire service would break.|
|The ability to design APIs for integrators. There was no need to design the architecture for integrators. API handled that.||

###Centric API
The arrival of new platforms has strongly shaken up the previous approach, which, although some problems, successfully worked in the previous conditions. More precisely, the arrival of mobile devices and the increasing traffic from them forced us to take the new platform seriously and made us realize that we needed to make the API a central part of the service.

![Centric API](https://images.prismic.io/superpupertest/d8e30140-6978-4c0a-a049-d16a8f77ba18_API_5.png?auto=compress,format)

So we got an API-centric approach, where API became the main core of the architecture that refers to a single database. The clients in web, mobile and desktop applications were separated from the core architecture, contained a minimum of service logic, and became rather simple and fast to develop.

![Microservice Architecture](https://images.prismic.io/superpupertest/f812aecc-1b57-4e37-89a9-6a4f4f57d08a_API_6.png?auto=compress,format)

Also, this approach went further and eliminated the single base, making it distributed for each service. At this point, we had a microservice architecture, which closed many of the early fundamental problems of monolithic architecture.

Not to be repetitive, the best illustration here is the waiter example in the beginning, only with the remark that the waiter may be the restaurant owner and knows more about it than any of its best employees.

|**Centric API advantages**|**Centric API disadvantages**|
|-|:-:|
|Code Reuse. The same code responsible for the core logic of the service is always ready for quick and easy access to different platforms.|Difficult Development. It's quite hard to develop your own high-quality API which implements all the above advantages.|
|Simple Integrations. Thanks to API, it's possible to provide access to your service much easier and faster.||
|Simple Clients. The development of the client part can be simple, fast and rather cheap.||
|Low Component Dependency. Not only integration problems but also customer congestion will not break your service.||
|More Control. We obtain much more control over each separate system component and, therefore, the whole system.||

###Economy API
It's clear that most needs are the same because interaction scenarios with any service are largely predictable and finite. The customer needs the service's functionality, the administrator needs to monitor the service, and the developers need a simple and convenient way to develop clients and integrations. 

But it was still difficult to cover these needs properly by developing a really good API, and not everyone could do it. So those who were good at it quickly realized that an API could be a great product on which anyone could build their service. So began to form the [API Economy](https://www.forbes.com/sites/ciocentral/2012/08/29/welcome-to-the-api-economy/?sh=235f1bb03a21), where to develop your own service, you can choose from a variety of open APIs, allowing quick and easy access to their functionality.

##API first development

Now you understand why it was important to consider not only the history of the technical aspects but also the commercial ones. The combined result of all the previous architectural decisions and business strategies was the formation of a new approach to service development itself. 

This new approach was API First Development, where we put our own API or the most suitable API available on the market in the core of our service architecture and then build our infrastructure around it and develop web, mobile or desktop clients in accordance with it.

Even big companies like Amazon, Uber, and Netflix, whose solutions were already very successful with a monolithic architecture, have switched to this approach. They moved quickly to microservices architecture and developed their own high-quality APIs, which allowed them to scale their services even more easily to various platforms. 

Probably the most illustrative case was when Instagram first launched only as a mobile client for iOS. Despite quickly gaining a user base of 14 million, the company was in no hurry to enter other platforms. However, having developed its API, which was quite successful, and making it available to the public, Android and Windows clients from third-party developers quickly appeared. As a result, the company developed their own clients for these platforms later. Still, even before that, they got a huge flow of new users without redesigning the entire architecture and without spending anything on client development.

So now you can easily make your own client for any services using their open APIs. For example, you can make your own handy client with an advanced set of features that will allow you to publish content on Reddit by using [their open API](https://www.reddit.com/dev/api/). 

Or, for example, do you want to build your own crypto-exchange or NFT marketplace? Please, take the [open API from Binance](https://binance-docs.github.io/apidocs/spot/en/#introduction) or the [open API from OpenSea](https://docs.opensea.io/reference/api-overview) and get real-time access to exchange rates and tokens, as well as easy and simple integration between those services and yours.

>Looking at recent estimates, in a survey by Postman, 61.9% of businesses rated themselves as at least moderately API-first. And a 2021 survey revealed that 78.2% of companies plan to increase or maintain investment in APIs within the next 12 months.

With almost three-quarters of businesses (74.3%) using more than five APIs per year, there is a big market for startups. 

The ultimate example is Stripe, which has risen to annual revenue of $7.4B off the back of an API-led model.

###Is the API first development flawless?

Of course, we see an excellent match between the desires of developers, businesses, and users. However, nothing is perfect. You can always find something to improve, especially if the standard solutions are not quite suitable for your service. Let's look at the great features it gains, but also the gaps we need to keep in mind.

|**API first development advantages**|**API first development disadvantages**|
|-|:-:|
|Code Reuse. We can use the same code as service logic for different clients.|Poor API Quality. When developing APIs, and especially when using those offered on the market, there is a probability that some of the logic is leaked to the client.|
|Scalability. We can quickly and cheaply develop clients for different platforms.|Sequential development. If you build development based on the API, the rest of the testing and development teams of web, mobile or desktop clients have to wait for the API development to be completed.|
|Flexibility. The emergence of new platforms does not force us to redesign the entire service architecture and allows us to adapt easily to new users' requests.|Problems in the integration phase. Some aspects of API development may not be accounted for and are only revealed during the integration phase, requiring bug fixes and again leading to waiting for the rest of the developers.|
|Reliability. Components work relatively independently, and this means that a breakdown in one place does not break the whole service.||

As you can see, we have all the same advantages as in the Centric API. But when you choose a really good API, they are brought to the absolute and become much more available. However, there are possible difficulties that require improvement in some cases. You won't necessarily encounter them, but a First Design API comes to avoid them.

###What is API first design?

API First Design is an approach where we start development not with the API itself but with the API design, where all the logic and infrastructure are specified in detail.

![What is API first design](https://images.prismic.io/superpupertest/a549932f-1fc1-487d-811d-7169a3de2ff7_API_7.png?auto=compress,format)

To do this, we will write a contract in an API description language such as OpenAPI. It is not the only one, but one of the best, so it has become a kind of standard. Then this contract should be submitted for review by experienced developers from different teams. After all the corrections and approval of the contract, you can start parallel development following the contract.

|**API first design advantages**|**API first design disadvantages**|
|-|:-:|
|The quality of the API is improved. Because all the logic and infrastructure are written into the contract in advance, the probability of errors is significantly reduced.|Additional resources. While writing a contract reduces development costs regarding bug detection and fixes, developing your own API is still expensive and complicated.|
|Low cost of error. Error detection at the contract stage is much cheaper than when writing the code.||
|Development speed increases. Since teams become less dependent on each other, parallel API development, client writing, and tests become possible in many ways.||

As you can see, there are disadvantages to consider here as well. However, this is an obvious improvement of this approach, and the above disadvantages may seem to like it only in the very beginning. In the long run, a quality API First Design at the core of your service offers amazing benefits and opportunities. 

##Summary
Now you know what an API is and how it has come a long way from a supporting tool to the core of most modern services. They owe much of their success to developing API as a technology and the consequent approaches to development and market states. 

Considering how many new devices, platforms and tools appear, it is impossible even to estimate how many millions of dollars were saved if companies had to rewrite the architecture of their services every time. 

And the example of many successful startups, the launch of which was much cheaper or would have been impossible without using APIs, is now a great motivator for a huge number of young companies. 

We at Mad Devs are always watching closely how technologies develop and what value they bring, and we have already experienced how the API First Development approach changes the rules of the game. So whether you want to use the established First Development API with all its benefits or go further and complement them with the First Design API depends on how you want to do your service.
***

*The original post is [here](https://maddevs.io/blog/api-first-approach-to-software-development/)*.