We just released our new version of our application Kurio. Fyi, for readers that still do not know what Kurio is, it’s an Indonesian news aggregator. If you’re familiar with how Flipboard works, then you will be familiar with Kurio.
A month ago, we just released our new version of Kurio, Kurio 4.0. In this version, there are many changes from the UX/UI, this is a total breaking change in our application.
Since it was a breaking change of version, there are also many changes related to API that we need to build (or even rebuild and refactor). And if you ever use Kurio, the comparison layout and UX between Kurio 3.0 and Kurio 4.0 can be seen below.
Development Process
We have 3 teams working together for the new version of Kurio. There’re Mobile Engineers, Backend Engineers, and Web Developers.
The Mobile team will develop the application Kurio 4.0, the Web Developer will build the web version of our application (can be seen in https://kurio.id/app) and the Backend team will develop the API for both of the Mobile and the Web.
Even we already have an existing API that provides API to Kurio 3.0, but to avoid unnecessary issues that will be raised and affect the old version, we decided to create a new API that will only serve for V4.
So there will be 2 API Gateway that will be accessed by the frontend. The old version for V3 and the new version that will be developed for V4. And the Backend team will be developing the new version of API for the V4.
API Driven Development
Since I was a Backend Engineer, I and my team will be working on the API side. We must ensure the API must ready as soon as possible so the frontend (Mobile and Web) can work on their side.
But because we start the sprint at the same time (the 3 teams). So it’s obvious that the backend team will block the other teams (Mobile and Web) to work because both Mobile and Web will depend on Backend side to provide the API.
That’s how we use the API Driven Development method to solve our issue. So every team can work parallel.
API Driven Development is identified with the API-first design principal. It means we must design our API first. We must create an agreement contract between Backend and Frontend (Mobile and Web). This contract is an API documentation that will be used by both teams (Backend and Frontend).
It contains the API specification and signature, authentication and authorization, resource and methods, parameters, types and data structures, etc. This contract was created and defined by both side Backend and Frontend and also based on the product features.
If both side already agreed, then we will start to work independently. The Frontend (Mobile and Web) will develop the frontend and application based on the API Docs, and the Backend will develop an API that fulfills the contract (API Docs). And with this method, we can work parallel without blocking each other.
Besides that, we also implement the API Driven Development method in Backend side.
So when the Developing the API for V4, in Backend side, there are many new services that will be developed, like a new feature that will be introduced in V4, a rebuilt for the old system that not structured well, etc. So there are a few new services that we developed for this new version, in total there a 3 new services, Collection Service, Feed Service, and Content Service, and this 3 services are connected to each other.
Feed service depends to Content and Collection Service. And Content Service depends to Collection service. Normally, people will think to work on Collection Service first, then Content Service, and then Feed Service sequentially.
But, that’s not how we do it. We just split the team into 3 teams. Each team will responsible for each service. Even when we have a meeting we will discuss all the 3 services, and everyone can work in any services, but just to make it easier for management and delivery, we separate a few people just to focus on specific service.
And then, this 3 team (the backend teams) will work independently and parallel based on API Docs that we will agree and defined at the beginning of the sprint. And that’s how we all the whole team from the backend (consisted 3 teams) to frontend working with API Driven Development method. Either it with the frontend, or also with us between the backend Team, we work independently using the agreed contract that is API Documentations.
Using Open API 3
Open API 3 is an API specification. It’s a new version of Swagger, that previously named Swagger 2. And instead of using a new name like Swagger 3, the Swagger team use the term Open API 3. Whatever the reasons, you could read more about it on their official website.
In simple, don’t be confused between Swagger 3 and Open API 3, it’s just the same thing with a different term.
So, back to our topic in Kurio. Previously, in Kurio in Kurio 3.0, we use APIB (API Blueprint) for our API documentation. But, when developing this new version of Kurio 4.0. We agreed to use Open API 3. Because APIB is not common and already abandoned, besides the community behind it, is not as big as OpenAPI 3 have. Open API 3 is more widely adopted right now.
Any details about Open API 3 Specification can be found in the official websites. It explained well over there. The differences and the new feature introduced since Swagger 2 also explained there very well.
So, what the benefit that we seek using this Open API 3?
Generate SDK with Open API 3
Just like this post Leveling Up API Documentation by M Rifad Ainun Nazieb we generate SDK based on API documentation. In that post, you will found, how we write our API Documentations.
But, it’s in Kurio v3. That time we still using APIB (API Blueprint) as our API specification, that will be converted into Swagger 2 and then generated into an SDK. And this SDK can be used as a library to any project that needs it. (Read the article for more understands about this meaning here :D)
We also need to do the same with Open API 3 because when developing the V4 we’re using Open API 3. We also need to find the same tool we have when using APIB. A tool that will generate an SDK from an API specification.
Luckily we found this projects https://github.com/OpenAPITools/openapi-generator. This project will generate the SDK client that will help us to do an API call. We won’t be bothered to create an API call handler by our self, because this project already generates all the boilerplate that we need.
Actually, this feature already exists in Swagger 2, but since we using Open API 3, this the only one tools that really satisfied us. Even when using this there are a few “customizations” that we made in our internal usage, but this one is already helping us a lot.
But why we need an SDK?
When working on microservices projects, means there are many services that connected to each other. And each services doing API Call to other services based on its need. So, we create SDK to help us to create a library that will help us to build our API Call request to any services. So we don’t have to create any request builder anymore, we just import the SDK and use it.
For example. This is an example of fetching content from our content services with Golang (we use Golang in Kurio), without using SDK.
Look for the function getArticleDetail(), I create a function to build an HTTP request to other services.
And then, imagine that we creating this in every project, in every endpoint. This is will be a redundant thing and boring jobs to do this. But with using SDK, all this process already handled by the SDK, and we just receive the response and the status.
We don’t need to create all the request builder and set the configuration. We just pass the base host, and let the SDK handle all the process.
By using this kind of method, we can cut all the boilerplate process for API call when developing our service that depends on other services. And it will speed up our development process.
Create Mock API Server with Open API 3
Another benefit that we seek with using this Open API 3, it helps us to create a mock server. Again, instead of creating a mock server tool, there is a project that already handles this, it is https://github.com/danielgtaylor/apisprout.
You could see that project for the details. It will create a mock server that will represent a real API based on the defined Open API 3.
So, even we’re still working on the API services, any client that depend to our services, we can serve them a mock server based on Open API 3 that already we defined in the first sprint.
For our case, our client as the Backend team is both Mobile and Web Developer. We then create a mock server that really-really represents the real API to them based on the defined Open API 3 that we used, so we (Backend Team) can focus to work on our API services.
Conclusion
So to summarize, here in Kurio, we use Open API 3 as our API specification. And also we use the API Driven Development method to build our product.
With this kind of method, we can achieve the optimal ways to develop our application from Backend to Frontend (Mobile and Web) without blocking and delay. Because everyone can work independently. Everyone has the same references or contracts, so there will be a minor error even nothing when doing the integration and connecting all the layer from backend to frontend.
*Distribution and Translation
Originally posted in: https://toolbox.kurio.co.id/api-driven-development-in-kurio-speeding-up-the-development-process-with-open-api-3-addcc07cb9ce
Bahasa Indonesia: https://medium.com/easyread/mempercepat-proses-development-dengan-open-api-3-8502011b7463
Top comments (0)