The following interesting key findings are revealed in a recent report by Postman: many developers are spending most of their time on APIs and they generally lack API design skills. 

A proposed solution in this report to help close the skills gap consists of “… 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 that are more aligned with the business requirements in your projects.  

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 identifying 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 the domain experts in your team. This approach is particularly efficient to identify 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 particularly useful to identify the boundaries in your domain that are candidates to become microservices. Indeed, one of the important challenges when working on microservices is to define the granularity and the boundaries of the microservices that will 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 different 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 then 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 and the resources candidates to use within APIs are found in stories and through the EventStorming workshops and correspond to Aggregates concepts as 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 is 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 the REST operations that will be exposed by your APIs. The OpenAPI files that you create will then be used by the developers to start coding the APIs while being aligned with the requirements you have identified and the design you have created. 

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 the requests from the external world. Your business logic is much better isolated from external changes by using this design.   

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 a free first call: 

About the Author

My name is Adel Ghlamallah and I’m an architect and a java developer.

View Articles