API-Design-First-Approach
Introduction:
In this article, I would like to cover the advantages of API Design first over Code first approach.
Code first approach:
In general, while designing API, we first start with analyzing business requirements followed by documenting low-level design to understand the various component interaction and implement code to achieve the required functionality. When the implementation is completed, API documentation is generated using Swagger Swashbuckle. With this approach, there is very little focus on API contract, URL, request, response, and return codes.
Design First:
In this approach, we first focus on defining API contracts, describing endpoints, requests, response objects, error codes, headers, and much more using API definition editors like swagger editor, kong, spotlight], etc. The tools will help you to design the API’s contract first before writing any code, share the document with the Architects community in the organization for the review, a developer can use the API definition document during implementing API. You can also use the swagger hub to review the API design. The API contract can act as the central draft that keeps all your team members aligned on what your API’s objectives are, and how your API’s resources are exposed. Moreover, you can target to comply with industry standards, for instance, TM Forum.
Swagger Editor: You can define the API capabilities, contract & schema using the swagger editor tool.
You can save the API capabilities as a JSON document.
Refer to the Github for complete code.
Code first approach documentation:
In most of the cases, once business requirements are implemented in the API, API documentation is generated using SwaggerGen which generates document using your routes, controllers, and models. You need to be a bit cautious with this approach if an action in a particular controller has multiple return statements as shown below. You need to decorate the action with ProducesResponseType to make sure that the swagger document covers all the scenarios. You also need to decorate the model objects with swagger attributes or XML document to generate detailed comments of request object properties for the API consumers. If you don’t add the attributes then the swagger will not generate API specifications properly.
If you use ApiController attribute on the controller then it does Model validation automatically and sends 400 bad request to the client. You can customize the error using ApiBehaviorOptions in application startup file. The options type looks as follows:
The above approach is the best way of handling Model Validation in an API or across all API in your application stack in the Organizational Unit. But this information is not captured as part of API documentation using Swagger when it’s generated from code.
Design First approach documentation:
You can avoid problems discussed in code first approach if you can directly use the swagger editor’s JSON document that describes the capabilities of your API to drive the swagger UI in .NET Core as follows. First, generate the JSON document in the swagger editor. second, use it to drive swagger UI as shown below.
Refer the JSON in .NET Core API
You can generate a JSON document from the Swagger editor and use it in the .NET core APIs for API documentation as follows.
- Add the JSON file under wwwroot
- Add Swashbuckle.AspNetCore NuGet package.
- Add following code in Startup.cs
- API documentation is generated from the JSON file.
- Implement your business requirement as per the API contract defined in the swagger.
Conclusion
The process is helping us a lot, where many microservices are brewing up to transforming a monolith application to micro-services.
