How to Implement API Design First Development

1. Introduction

Recently, I've been building a product for my Comic Book Artists Marketplace startup. For the MVP, it will have several microservices like IAM, portfolio, gigs, bookings, etc., orchestrated by a backend-for-frontend service. It will use REST API for communication, which initially, I planned to develop using Spring Boot. 

This is the code-first approach, and here are the problems I've encountered.

• You have to look at the big picture while developing the different APIs of each service.
• Language dependent, since I have chosen Spring Boot, it will be hard for me to migrate to another framework if I decide later.
• I have to at least code the REST endpoint stub and models so that I can call it in another service.
• I have to build the REST service to use it in another project.
• The service structure becomes a bit complex as I needed to create sub-modules for API (DTOs), app (endpoints), and client (Feign clients) so that I can add it as a dependency to other services without adding the app code of that service.
• You have to be in a specific class to define the documentation.
• Version management is a pain because you have to manually create each DTO and endpoints.

2. API Design First Development

As a solo developer, I realised this is not the way to go. And so, I looked for other methods. That's when I found the API design first approach or API-driven development. It's a practice that has been increasingly promoted recently. Any API development must start with the design process and iterate, where humans and machines can understand and create the rest of the application around them.

• In the API design first development approach, the OpenAPI Specification is the first artefact that needs to be created. It contains the contracts (endpoint name, parameters, request & response types, errors, methods, etc.).
• The API must be designed in collaboration between the FE and BE developers.
• Once the OpenAPI Specification is finalised, the development can be parallelised:
• The frontend developers can create the user experience and forms by mocking the request and response objects specified.
• The backend developers can develop the application's business logic with unit tests around the APIs, pushing test-driven development.
• QAs can start creating the test automation framework using the defined schema.
• When all of these are done. The integration testing can start with interservice communication in the backend, then responding to the frontend's requests and verifying that everything is all well with the QA automation framework. This process should not fail as long as the OpenAPI Specification is respected.

In my experience, these are the benefits I gained in using this approach.

• Language agnostic, you design the API without coding. I use Stoplight.io.
• For all users. The endpoints, parameters, and models are all in one place that even beginner developers can understand. It makes spotting an error easier. For example, wrong data type, false constraints, etc.
• Better and self-documenting API. Creating the documentation becomes much more accessible. They can be defined on every endpoint, model, parameter, etc.
• It speeds up the development iteration. I can quickly generate the API DTOs without doing any code or adding the API client as a dependency on other projects. I've chosen the DTO approach as there can be multiple versions of the endpoint.
• It makes version management easy. I can suffix my initial objects with V1 and then V2 later on.
• I can iterate the API development without doing any code. And it gives me so extra time to focus on other things.
• Microservice-based architecture. Since multiple services can be defined on a single project, I could determine the standard schemas and data models.
• I can generate the controller and client for testing.
• I can focus on business logic development.
• Split stack development. BE, FE, and QA can be developed parallel as the contract is respected.

Currently, there is only one tool I know that can aid me in API first design development, which is Stoplight.io.

3. How Does it Work?

3.1 API Specification

Using the editor, the lead developer design the OpenAPI Specification (use V3), which includes:

• Endpoints with parameters, request and response models, and errors.
• If resources are available, a local mocking server can be set up.
• Automation testing framework can be developed using Postman to test the OAS files.
• Once finalised, the OAS files are stored on the GitHub repo for API developers.

Style Guide

3.2 API Development

• Development of the API using any programming language. As long as it's supported by the OpenAPI generator (https://github.com/OpenAPITools/openapi-generator).
• Create a deployment pipeline for the developed API to be tested.

3.3 API Publication

• Create a deployment pipeline which verifies that the API specification is valid based on OpenAPI V3 guidelines and runs the automated integration tests.
• Once the build and test are successful, deploy the artefact in higher environments such as staging and production.

4. How it Fits Together

API Spec will be created and maintained in its own repository, different from the service with the actual implementation.

5. Development Process

As of when this article was published, no standard process defines the rule in this approach. But there are some guidelines defined by Stoplight.

Planning - The process begins when the business requirements flow from the Project manager down to the Product owner.

Styles & Guides Governance - Company-wide rules on how the elements of the OAS must be defined. For example, parameter names must be camelCase, a list should always have at least 1 part, a currency should be described as a BigDecimal and so on.

The styles can be overridden by teams.

This process is managed by the software architect. All specifications (endpoints, models) must be in a central repository.

API Contract - Defined by the lead developer in charge of the actual development. It must adhere to the styles and guides before and use the models in the central repository.

Mock Deployment - Once the API contract has been finalised the API can be mocked by deploying the OAS files in the Stoplight environment.

Note: They have a free plan, so don't be afraid to try.

API Development - Developers, can start the development of the services using the OAS committed in the central repository. They must generate the models for the specific version of the API and include them in the service project. This will allow multi-version support.

Contract Testing - QA should create an automation framework that would test against the fully functional mocked endpoints.

Documentation - Documentation is automatically created from the OAS files committed in the repository and deployed as a container or in an S3 bucket. It should be accessible to the respective parties that will use/consume the API.