Jani Swinnen

4 min. read

Writing documentation: Detailed Design in 8 sections

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:

  1. Revision History
  2. Main objective of the API
  3. List of endpoints
  4. Detailed Design per endpoint
  5. Artifact summary
  6. API Design decisions
  7. Solution Design decisions
  8. 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:

01.02.20241.0Initial 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.

Developers using detailed design at their clients

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.


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:

  1. Description
  2. Process diagram
  3. Process steps
  4. Sequence diagram


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:

  1. 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.
  2. A link to the Exchange asset for the APIs, as well as the name of the Mule Project.
  3. A link to the APIs GitHub repository and the Mule version in which the API was developed.
  4. 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.

  1. We describe the design patterns used in this API, for example, HTTP synchronous pattern, Messaging asynchronous pattern, etc.
  2. We make a list of all properties that are defined within the project. These are often the connection properties for connection to other APIs.
  3. 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.
  4. We have a section for possible alerts that are generated out of the project.
  5. 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!

Interested in a collaboration?