In this piece, I’ll be explaining why you should take a design-first approach when creating a RESTful API for a significantly larger, enterprise scale product such as the WSO2 Identity Server, and what I believe is the best way of going about doing that.
First off, when developing an API, either we can take a design-first approach or a code-first approach.
Design-First vs Code-First API development
In Design-First API development, the concept is first transformed into a human and machine readable format, such as a Swagger definition, and then, the code is developed conforming to that definition.
In Code-First API development, API is first coded to address the business problem. The documentation is created afterwards.
There are pros and cons for each approach, but generally, taking a design-first approach is recommended.
Why Design-First?
When you are working on a product in the scale of WSO2-IS, you, and everyone else on the team, are co-creating a product for the customers. Therefore it is critical that the whole team understands your solution and it’s possible impact on the product, as you intend it to be. In this case, an API contract (A swagger definition, most likely) can prove as a clear, effective medium of communication.
Another reason why you might want to go with a design-first approach is automatic code generation. There are readily available plugins for automatic code generation from the swagger definition. It saves an enormous amount of time for a developer compared to starting a project and creating directories from scratch. Also, you can update the swagger definition and regenerate and update the files conforming to the new definition easily with the help of these plugins. You can read more about how to automatically generate code from a swagger definition for a Rest API from here.
Furthermore, when adhering to a design-first approach, the API design tends to get much more refined and complete. Although defining an API from the outset may be a bit time-consuming, a well designed API helps you and your team in the development process to speed things up since it paints a clear picture of what the end product might be.
Hence, for an enterprise scale API development, such as in the WSO2- IS, a design-first approach can prove to be highly productive.
How to do it?
When designing a RESTful API for the WSO2-IS, the following fundamental steps should be followed. Although the graph might suggest that you follow these steps sequentially, it is not mandatory.
First off, you have to create a model of the data that is going to be handled by the API. From this data model, the resources of the API will be determined. For each of the resources, the representations supported by the APIs have to be determined. Next, these resources must be named properly by means of URIs (Uniform Resource Identifiers). For each of the resources, the HTTP methods that are used to perform the required application functions have to be decided. These includes the use of applicable HTTP headers such as POST, GET, PUT, DELETE, etc. Furthermore, the special behaviors required by the application (e.g. concurrency control, long running requests) has to be decided. Finally, potential error situations have to be identified and corresponding error messages have to be designed.
You can read more on the specific guidelines when creating a RESTful API for WSO2 products in general from here.
