Web API-first architecture approach and third party integration
Almost every company nowadays uses APIs in nearly every business process. From marketing and sales (Google Analytics), project management (Jira/Zoho) to communication (Firebase Cloud Messaging), which means that APIs can impact every part of our business. They reduce the risk of failure by ensuring reliable solutions, consistent and easy for developers to use. APIs are gaining more importance in the development process. They are considered the most important part of the entire project more and more each day. Here we come to the ‘API-First’ approach, but let’s start from the beginning.
In the beginning, there was a REST…
Starting with the methodology, REST (Representational State Transfer) is a software architectural style that defines a set of rules to be used by us for creating uniform Web services with a predefined set of stateless operations. Using web services, systems and applications gain access to create, read, update, or delete a document, file, or information in any format on the web.
We grant access depending on the endpoint (URL address where the resource or action is available), request method [GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, OPTIONS, TRACE] and information contained in the request headers, such as information what format the data is sent to the API, or those allowing user authorization. By using a stateless protocol and standard operations, RESTful systems focus on fast performance, reliability, and scalability by reusing components that can be managed and updated without affecting the running system.
Then there were APIs…
Let’s clarify what Application Programming Interfaces (APIs) are. Without being original, I will use the most common API comparison – the restaurant.
User is the customer, API is the waiter and Backend is the kitchen. Customers do not talk to chefs directly, or at least I have never witnessed such an event (who would like to share secrets of their recipes anyway). They pass their orders to waiters, so they can send them to the kitchen and return with the tasty dish. Order here is selected content from the menu, the waiter is a piece of code that handles data (previously described as REST request) provided from the customer, and the dish is the response provided by the kitchen (endpoint).
We know the basis so … What exactly is the API First approach?
It means that we think about the API as being the most important part of the project and as the core requirement to most, if not all functionalities in the application or applications. Instead of starting the development of our application from server setup, containers, or databases, we start it from an API layer that will communicate with the audience. That might sound like starting the work from the middle at first, which is odd, but it makes sense when we think about how huge work API is doing in applications communication.
The commonly used practice is where developers start from creating backend functionalities and then put API creation (exposing existing functionalities) at the end of the process. If we compare it to the situation where we need to build the hospital, the “API First” approach would focus on ensuring that the paramedic (API) has the easiest way from the ambulance drive to the hospital emergency ward, rather than having to go up the golden stairs with the patient in a wheelchair, through air-conditioned hallways.
How it is working?
Before we start looking into the webpage, PC app, mobile app, or any other, we are setting a list of things that API will need to fulfill. To provide the highest digital value it is highly recommended to do this the “Outside-in” way instead of “Inside-out”. The difference between “Inside-out” is that we start our development from designing API experience first by thinking about what user/developer/application would like to receive, then designing it and developing it at the end. Doing otherwise by developing functionality and then thinking about how we shall provide it to users, will create in almost all cases a need for additional development/rework which is unneeded cost and frustration.
What we need is to:
- Determine our API – will it be a service, interaction, or product?
- Check what are limitations, for example in the case of mobile applications – what should be stored on the server instead of a device?
- Write down types of data that identified key actors (users/applications) – should be able to Create/Read/Update/Delete or interact with in other ways?
- Check who the audience is, what is the main problem of the audience. As we will not be able to solve all generic problems, understanding, addressing, and prioritizing the most important problems is the key to an efficient production process.
- Determine what type of authorization needs to be implemented to secure our API [Bearer token, Cookie auth, OAuth etcetera].
- Establish unified rules by which all APIs will be working (endpoint names, response codes, methods names, response body etcetera…)
- Determine how users/developers are going to achieve scenarios, (as we can achieve single interaction in plenty of possible ways, we need to select one).
- Preparation of API documentation that will be provided to developers to maximize ease of implementation.
API “Design-First” and API “Code-First”
Contrary to popular belief, “API-First” is not synonymous with “API Design First”. The fact that we adhere to the “API-First” philosophy does not mean that we cannot generate documentation based on the API controller code. The “API Code-First” approach is more traditional, and it has both pros and cons.
So what’s the main difference? As the name suggests, “API Design First” documentation is the output of a design, not a code. The API team creates a contract (not only human but also machine-readable API documentation based on specification, for example, “Open API”) which could be made in popular API tools like example Postman or Swagger. Afterward, it is used to build the code.
“Code-First” provides documentation based on the API code created by the developer. It can be written by the developer itself as well as generated from code.
When the “Design First” approach is more effective?
“Design First” seems most efficient in situations when the target audience of the API is clients or external partners. Software as a service is a perfect example. In this case, our API is a key distribution channel that our end customers will use to access some service we provide. Then good design brings long-term benefits until the end of the project. Such a correct setup API is then self-explanatory and can be shared with potential users. Its implementation does not cause problems which is the big factor in end-consumer satisfaction.
Prepared API contract may serve as the draft that keeps all our team members aligned on what our APIs objectives are, and how our APIs resources are exposed to applications. The human-readable design also is easier to test. Finding issues before writing any code is much more efficient as it does not require any rework on the developer side.
So what about the “Code-First” approach?
Developers can start implementing the API much faster if they start coding the API directly from the requirements document. This is important if speed and agility is the most important factor for your API. The fact that automation is much easier in the “Code-First” approach helps strengthen this case, with a lot of frameworks and libraries supporting scaffolding server code, functional testing, and deployment automation.
The team can improve development speed a lot by automating and reducing the complexity of the process, but it requires experienced staff members with wisdom on how to use these tools efficiently. If the API will only be used by the team or company that’s developing it, then the “Code-First” approach is an ideal solution for us. This is especially true if the API developed is small with only a few API endpoints and will only be used internally, for example, to manage in-application data exchange.
The Benefits of an API-First
An API-First approach to building products is very profitable. Examples of benefits include:
Happy developers are efficient developers
If we start from documentation, then there will always be time for documentation. Developers always lack time and willingness to prepare documentation at the very end of the project, and such documentation, made quickly and inaccurately, is not user-friendly. APIs are almost always used by developers. API’s first approach ensures that developers who consume it will have the best experiences. Good design, logical and clear documentation, provides positive developer experiences, and reduces the implementation time.
Reduces the cost of developing apps
APIs and code can be reused on many different projects. When a development team is building a new app, they don’t have to start from scratch as they can reuse existing code. API-first also allows most problems to be solved before any code is even written.
Increases the speed
Automation and frameworks significantly speed up the development of APIs and applications. The “API first” approach allows us to add new services and technologies to applications without having to recreate/redesign the entire system.
Conclusion
It requires some planning and organization. In return not only injects harmony into the process but also allows swifter and cheaper development. Day after day APIs become not secondary, but main functionalities of applications. The sooner we realize it in this multi-platform world, the more we can gain.
If you want to see unusual VR and AR projects, I invite you to visit the PORTFOLIO.
