At our customers, we prioritize the usability of our APIs In order to accomplish this, we write what we call a “Detailed Design” page for each API we develop. This Detailed Design page is always generated from our template containing 8 sections:
- Revision History
- Main objective of the API
- List of endpoints
- Detailed Design per endpoint
- Artifact summary
- API Design decisions
- Solution Design decisions
- Postman Collection
1. Revision History
The revision history is a simple table element where we keep track of which developer added which sections to the Detailed Design:
| Date | Version | Description | Author |
|---|---|---|---|
| 01.02.2024 | 1.0 | Initial version with: • POST /idoc | Jani Swinnen |
Revision History Table
We keep track of the date the endpoint was added, as well as a short description of the changes and the person who made those changes. Lastly, we give each revision a version number so we can easily see in which order the changes were made.
2. Main objective of the API
In this section, we outline the main objective for the API, which is a core concept of Mulesoft’s API-led connectivity approach. By defining a main objective for the API we can keep the API’s usage focused on that goal and easily determine if a new functionality would fall within that goal’s scope.
Objective The API will be responsible for receiving requests from SAP ERP System that wants to obtain different kind of information
3. List of endpoints
Next, we list all the implemented endpoints so the end user can easily get an overview of the available endpoints in this API.
The API has the following endpoints implemented: • POST /idocrouter • POST /sdfc/attachmenthandler • POST /products • POST /vendor/pricing
List of endpoints for an API
4. Detailed design
After the general documentation, described above, we add a detailed design for each endpoint. Each detailed design consists of the following parts:
- Description
- Process diagram
- Process steps
- Sequence diagram
Description
The description section of a detailed design includes the endpoint URI and HTTP Method as well as a short description of the functionality of that endpoint.
GET /events/installation Query installation events for the desired products within the specified time range
Description section of the detailed design
Process diagram
The process diagram section consists of a process diagram that visualises how the endpoint functions. We often design this using the Gliffy add-on for Confluence. Each step in this diagram receives a number, to which we will refer in the next section of the detailed design.
Process steps
After the diagram, we describe each step in more detail. In this section, we also add the mapping specifications we used for Dataweave transformations, as well as the URIs for possible calls to other APIs.
Sequence diagram
In the last part of the detailed design, we include a Sequence diagram – also designed using Gliffy – that visualises the complete call sequence within our API architecture. This allows the end users to see how the calls traverse the API architecture.
5. Artifact Summary
After the detailed designs, there is a last section containing some last details. Starting with the artifact summary, which consists of the following:
- A link to the API specification project on the Mulesoft Design Center. This allows us to quickly find the corresponding RAML specification for each of the APIs.
- A link to the Exchange asset for the APIs, as well as the name of the Mule Project.
- A link to the APIs GitHub repository and the Mule version in which the API was developed.
- A list of the application names for each of our environments.
6. API Design Decision
The API design decision section describes both the API design conventions that were used as well as the security schemas in use. The security section can differ quite a bit from system to system. For internal communication, we often use Mutual TLS, but for external systems, it depends on what those systems support.
7. Solution Design Decisions
The second to last section handles the decisions made while preparing the solution design.
- We describe the design patterns used in this API, for example, HTTP synchronous pattern, Messaging asynchronous pattern, etc.
- We make a list of all properties that are defined within the project. These are often the connection properties for connection to other APIs.
- We do the failure point analysis, where we analyse and predict the different ways the API can fail. This is a nice start when trying to troubleshoot errors in the API.
- We have a section for possible alerts that are generated out of the project.
- We list the logging strategy used in the project.
8. Postman Collection
And lastly, as part of the detailed design for each API, we include an export of the Postman collection, to help other developers in troubleshooting by letting them import the test data and requests used during the development. This collection often includes the requests to the local environment when debugging/running the application, and the requests to the DEV environment on Cloudhub.
Are you with us?
Interested in working this way yourself? Or do you believe our way of working could help you as a company? Reach out!
