Motivation¶

The landing page provides general information about the importance of APIs, PSS®X vision and strategy.

In a large-scale system, APIs play a crucial role in enabling the system to communicate with external applications over the network. By providing a standardized and secure way for the system to exchange data and interact with other applications, APIs enable the system to integrate with a wide range of external services, such as geographic information system, network model platforms, and data sources.

Following common guidelines helps development teams focus on the actual APIs instead of discussing the same topics over and over again, and therefore supports faster development cycles with more customer value.

The following picture summarizes the activities that need to take place when we want to develop a microservice-based application by adopting the DDD approach.

Figure depicts the three activities and their interrelations:

requirements elicitation and analysis,
design
implementation and testing.

During the requirements elicitation and analysis, three subactivities take place:

the application requirements are stated in features with and from users by following the BDD approach;
the information model, as part of the domain model, is created by “crunching knowledge” with domain experts;
a prototype is designed and is discussed with both the user and customer

The design of the microservices is comprised of the sub-activities involved in:

designing the domain.
designing the api (we are here !).

Based on the UI/UX design and further discussions with the domain experts, the information model is refined, e.g., design decisions are made, and design patterns from DDD are applied.

The system is divided into subsystems that, according to Conway’s Law, can be realized by individual teams using bounded contexts.

After this preliminary work, the microservices are implemented and tested. The web APIs describe the microservices’ entry points. These entry points and their application logic are implemented and tested, as the microservices’ domain model. The features from the application analysis are used to test the application.

The ubiquitous language is central to the use of DDD, therefore, we introduced a glossary to capture the domain terms. Each term of the ubiquitous language is listed and described by a few sentences

Strategy¶

A Web API can be used to coordinate microservices in the mapping of a complex business workflow onto the area of microservices or to offer business functionality to third-party developers. To facilitate the reuse and discovery of existing microservice functions, the exposed web APIs should be designed with care.

When designing Web APIs for a large-scale system should adhere to the following informal quality criteria:

The result of this design approach was finally structured according to the specifications of OpenAPI, which has the goal of “defining a standard, language-agnostic interface to REST APIs, which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

Understand the example guidelines and use recommended tools to evaluate and improve your APIs.