Last updated on December 4th, 2022 at 07:11 pm
The following interesting key findings are revealed in a recent Postman report: many developers spend most of their time on APIs and generally lack API design skills.
This report proposes a solution to help close the skills gap: “… more training, more education, and more tools and services are needed …”. The report also mentions that “… things are getting more business-aligned … there’s been that classic IT/business divide for the last five to 10 years; where developers are doing APIs, but now we’ve got a lot more, business stakeholders”.
Indeed, aligning the APIs with the business requirements by improving the modeling and the design of the APIs being developed is critical to the success of a project. The following are practices that help better build APIs more aligned with your projects’ business requirements.
For gathering and documenting your requirements, you can use the classical user stories or, even better, what is called Job Stories that focus on the triggering event or situation, the goal, and the expected outcome as illustrated in the following example:
When _____ , I want to _____ , so I can _____ .
The sentence that comes after “I want to” identifies the capability the customer wants. After “When” is for determining the trigger events, and finally, what comes after “I can” defines the expected outcome. The stories will help you understand the requirement and identify the capabilities used in modeling your APIs.
Using the Domain Driven Design (DDD) approach will help you discover and understand the business domain through a collaboration between the technical and domain experts in your team. This approach is particularly efficient in identifying the terminology of the business domain (ubiquitous language) used by the domain experts, which will facilitate your communication with the domain experts and reflect this “ubiquitous language” in your design and code in such a way that the code will be more aligned with the requirements.
The DDD is beneficial to identify the boundaries in your domain that are candidates to become microservices. Indeed, one of the critical challenges when working on microservices is to define the granularity. The boundaries of the microservices that compose your application and the DDD approach will help you in this regard.
To help you use the DDD approach, I propose that you use EventStorming workshops where participants (domain experts and technical members) meet in collaborative sessions and use stickers with different colors to work collaboratively to understand the business domain where concepts are identified, including domain events, commands, actors, aggregates, …etc.
Once the boundaries have been identified, candidate APIs and their scopes are defined using the DDD approach. It comes time to focus on defining the operations that each API exposes. The operations are driven by the capabilities identified in the Job stories in the requirements analysis step. The resources candidates use within APIs are found in stories and through the EventStorming workshops and correspond to Aggregates concepts defined in DDD.
Next, you need to focus on the design of your APIs and avoid the temptation to start writing any code until you have sketched your design. This approach is called API-Design first. In this phase, you will use the information from the previous phase (modeling): the APIs, the operations, the resources, and the URIs to create a “specification” that describes every API or what is called a contract that defines the purpose and functions supported by each API and satisfy your modeling.
To create your contracts, use OpenAPI specification (aka Swagger) to describe the design of your APIs, including the operations, resources, input parameters, and REST operations that your APIs will expose. The developers will then use the OpenAPI files you create to start coding the APIs while being aligned with the requirements you have identified and your design.
Last but not least is to use Hexagonal architecture to cleanly separate the layers of your code inside your APIs. This architecture, also called Clean architecture, makes your code easier to test and makes your business logic (domain layer) independent from the Databases and the front controllers that receive requests from the external world. Using this design, your business logic is much better isolated from external changes.
If you are in the process of transition/migrating to microservices and you are looking for insights to help you go through your process, feel free to send me a message to set up a free first call: adel@softwarearchtectskills.com