Contract first. Integrate then. Implement last.
Any society is impossible to mind without communication between people in it. And group of people without communication are not able to live together in an organized way, make decisions about how to do things and share the work that needs to be done.
And computer programs behave the same way. They are united to special groups where they live together in an organized way, make predefined decision about how to do things and share the work that needs to be done.
Such special group is called “cluster” in software development. And cluster as any society does not make sense without communitcation between programs in it.
But how programs communicate to each other?
Programs uses network that is similar to people one. It looks like a post office where program could send a letter with some information. Program may ask for something in letter or maybe tell about some event.
But despite of people communication program one is limited by predefined communication patterns. Such patterns are called API (Application Programming Interface). So, API represent a contract how to speak with particular program. And it looks like a piece of cake to define contract and just to develop client of API.
But reality is different.
Why is difficult to develop API?
In reality, developing software to support API could be painful process, prone to a lot of bugs and refactoring. And it is no program’s fault because misunderstanding in API is reflection of misunderstanding between people who develops software.
Why misunderstanding happens?
Let’s take a look on two common approaches to develop API before to answer to this question:
- Contract last
- Contract first
Contract last approach states that developer creates program implementation first and then define API contract depends on its implementation. Contract first approach states that developer must define API contract first and then create program implementation depends on API contract.
Nowadays, contract first is the most popular approach, but nevertheless misunderstanding happens in each project that I have involved.
Why? — I ask myself.
So, I started to research this issue and soon I realized that misunderstanding happens when someone try to use API in practice.
But why? — I ask myself again. — Why does misunderstanding happen if API contract already exists?
So, I found some analogue to this. API is a quite similar to UI. It could be beautiful in its structure like UI appearance and it also could be handful in codding behind API, but it could be awful in API experience like user experience (UX) with UI.
API experience (APIX) — that is root of misunderstanding.
API experience (APIX)
Let me show example from one of the project that I have envolved.
As project architect I created REST API for back-end application. Also as back-end developer I created implementation of this API on back-end side. Front-end developer created beautiful UI at the same time. So, the last point in dev roadmap was supporting back-end API on front-end side.
- I could not understand where I should get data for this form? — front-end developer said to me.
- Use this data structure in API, — I answered him.
- It is difficult to support such data structure, — front-end developer said after a while.
- Why? — I asked him.
- We prefer flat data structure on front-end but API models has complex data structure with a lot of enclosed custom data types and collections. It requires to create complex code to transfer data from received JSON to UI forms, — front-end developer answered.
I was upset. Really. I spent 6 weeks to create API and back-end implementation. I made a lot of work: created domain model, developed REST API according to best practices, developed implementation with code lines over 10 000, wrote a lot of tests. And now I heard that API is not usable and my work is waste of time.
It is really to hard overcome this negative feelings and redevelop API and back-end application in new way. I did it. But project deadline was comming and I had to make some workaround. Therefore, I spent 1 day to find out solution with minimum effort to refactoring and 3 days to implemented it.
Why I did that?
Because it was my fault I did not get APIX into account. It created misunderstanding between front-end developer and back-end one.
API integration before implementation
I have a lot of similar cases in my development practice. And I tried to find out solution for this issue. And I found one:
It means:
FIRST. Create API contract between two programs.
THEN. Integrate two programs using created API.
LAST. Develop implementation related to API in each program.
Why integration is needed?
Integration between API consumer and API provider like a test. You verify API experience that API is easy to use and suitable for both sides.
Why API integration placed before implementation?
There are two reasons.
First, most of developers (like front-end, back-end) believe that API is only responsibility of API provider, namely back-end service that provides API. And I agree with such meaning in case of API as Service.
But I completely disagree with such meaning in case of API between sub-systems at one service. In this case, API contract like an arrangement. It means two people or groups decide how communication happens between programs.
Therefore, both side (API consumer and provider) must be involved to API creation process.
Second reason is difference between theory and practice. Contract first approach states API contract should be created first and only then implemented. It means theory first and practice then. But, most things to be known better only in practice rather than in theory. It is not fault of Contract first approach because human brain works in such way. Therefore, learning by doing is one of the most effective technic to learn something quickly.
So, API developer think that API is handful when he developed it in theory according to Contract first approach. But in practice, API consumer could have a lot of issues to works with that API. And API consumer usually asks to change API. And any API changes have very high cost if API has implementation behind it.
Therefore, API integration should happen before its implementation in order to reduce development cost and save time and effort in development process.
What about practice?
Ok, in theory it looks like working solution. But how to bring it into practice?
From API consuming point of view, there are two relations:
- One API provider to One API consumer
- One API provider to Many API consumer
Point to notice:
Lack of consumer means that there is no consumer of API. From my point of view, such API makes no sense and such case is not considered in article.
Let’s look on each relation in details.
One to One
It is the simplest relation between API provider and its consumers. The most famous usage case is communication between front-end application and back-end one.
First, API contract should be created. It could be WSDL, Open API or another standard of API specification.
Then, API provider should supply service without implementation of serving incomming HTTP requests. It means API provider must only receive HTTP request and return predefined response like a mock service.
Point to notice:
I recommend to use code generators to speed up and simplify such activity in case of API changes during integration process.
On another side, API consumer should supply service without bussiness implementation in order to check API experience. For example, there is no needs to create UI with styles or some business logic. It means you can put some plain inputs somewhere on page, without styles and best practices, then call API endpoint and transfer data from API provider response to this inputs.
The goal of API integration process is to check API experience (APIX).
Does it suit for both side? If it is not, then change it. Without business logic implementation any changes are simple to do.
Last, develop HTTP request serving logic on API provider side and business logic on API consumer side after APIX has succeded on integration stage.
One to Many
I know two approaches to handle this relation:
- Force to support API as is (API as Service)
- Split One to Many case into many One to One cases
Force to support API as is (API as Service)
It could be useful in following cases:
- amount of API consumers is very huge
- API consumers implemented by various vendors
The simplest example is Twitter. Twitter has API but there are numerious Twitter API consumers. In such case, Twitter supply its API as is and other API consumers have to support it as is too in order to get some service from Twitter. In such case, usually API consumer interesting in communication with API provider.
Split One to Many case into many One to One cases
Sometimes there is communication between several web services developed by different vendors. In such case, both sides are interested to communicate to each other. And usually no one would like to change its API for another side. Such task dramatically becames hard to implement in case of several participants in communication. Because it requires to synhronize API for all participants.
How to solve it?
Split One to Many case into many One to One cases. Of course, each side could create new contract and embedded into its service. But such approach is tight coupling that has a lot of disadvantanges and using loose coupling is preferable in software development. And one of the most popular solution is to create mediator or broker between each pair of web services.
Mediator or broker support API of both web services and usually perform mapping between its data structure.
Point to notice:
There are some various patterns based on this concept like Enterprise Service Bus (ESB).
In such case, mediator or broker represent API consumer for each API provider. And sometimes it is required to make changes in existed API in order to implement integration between two web services. And I recommend to create contract first, integrate then and implement last in such case.
Conclusion
Programs have API in order to provide capability to communicate with them. Like a people, sometimes programs could be selfish and provide its API as is. And API consumers are no choice to support it as is. But sometimes it is possible to change programs API. And for this case, I recommend to create contract first, integrate then and implement last because API is interest of both side, API provider and its consumer.
