MuleSoft API documentation template

Before we start talking about Mule API documentation lets first create a scenario, by scenario I mean an Interface.

But first, what is an Interface?

An interface in Middleware is nothing but a API integration where the goal is to integrate two or more systems. Commonly, API integrations are also referred as interfaces. It is something which the Business users need. So, let's define a simple scenario/usecase.

Scenario

Your client choose SAP as their ERP to streamline operations, reduce inefficiencies in their company. There are various Business units/teams/processes which participates in this massive ERP operation and each Business unit leader has a goal to integrate their processes to other units. One of such unit is the Accounting. The Accounting team wishes to migrate their data from their legacy applications to SAP S/4 HANA, shortly called as S/4. Here both the source and target systems are exposed as APIs with which you are a MuleSoft dev can interact with. We do not need to know what the business would do with the data which is processed once it reaches S/4. Our goal is to propose a design and implement it. But since our discussion is about writing Mule documentation, lets just imagine you have finished your design and about to implement it in code.

So what's next? You guess it right if you said `start preparing API documentation and get the approvals to proceed with dev work`

Types of API documentation

Now before we proceed to see the table of contents of MuleSoft documentation. We need to know the different types of documentation.

TLDR; each organization has their own way of doing things and documentation also varies from client to client. Some clients categorises Mule docs into a

High Level Document (HLD)
Low Level Document (LLD)

In some organizations, they refer to the same above things as

Interface Design Document (IDD)
API Design Document or APP Specific Design Document (ADD)

But if we try to generalise this, High Level Documents and Interface Design Documents are more or less the same, and the same is could be true with LLD's and API Design Documents.

Now, our immediate question will be, what does HLD/IDD and LDD/ADD encompass?

What is an Interface design document?

An Interface design document is a High level mulesoft API document which consists of the Design specification which needs to be implemented for an Integration of two or more systems. The key words here is "needs to be implemented". Meaning, this is the kind of doc which is prepared before the actual mule API implementation takes place.

What is an API design document?

We now know what an Interface design doc is. It capture all the High level specificiation details on the overall interface/integration. The terms `interface` or `integration` usually is referring to the whole end to end design (E2E) from the mule developers perspective. A single interface can host many APIs, and unlike individual mule API which are individual packages of their own, an interface is not a real thing. Its an invisible unit which defines or talks about the one of the goals of the business processes. Meaning, interfaces add meaning to the business users, and APIs add meaning to the Mule developers.

So, what is an API design doc again? Its essentially a low level specification document which captures all the low level details of each individual mule API bundle.

Also, such low level docs are ideally meant to be prepared only after the design is implemented in code and submitted for review.

Clash between Devs and Supervisors

There is no point in preparing an API level document when the requirements from the business and the developer idealogy keeps changing throughout the period of development phase. Once there is a concrete design and everything is set, implemented and accepted and move to production, only then a low level document can be of any use to whomever is supporting that interface in production.

But in reality, this is never the case. Devs are rushed by their supevisors to prepare all the docs unfront, because supervisors also excercise caution against the devs mentality who could potentially leave things ignored once an interface is moved to production

Who is to blame here? on one hand to a dev it does not make any sense to prepare API docs for something which is not even developed yet, and on the otherhand what if the developer ignores prepare the doc once the apps move to prod? Also, what if the dev forgets whatever he did for that interface he owned? What if he lost touch in it since he is working on some other Apps for a very long time? It is a high possibility.

Moreover, with some clients there is no documentation and standard practices to follow. I personally think that documentation is necessary and must be always encouraged to make the lives of others who support the project easy. However, it must be done right and not in haste. It only makes sense to finish the implementation and then prepare the low level document, but instead of having it as a separate acitivity like a group thing in a sprint two months down the line, make the individual devs prepare their docs right after implementation completion.

But here is the thing. Among the HLD and LLD, HLD takes more precedence. A HLD gives the reader quick insights about the setup, the workflow, special requirements, constraints, point of contacts etc regardless of whether the reader knows MuleSoft or not.

LLDs are meant only for developers use. They are never meant to be shared with business users. The person who supports your mule code after you leave the project needs the LLD the most.

But I have to say, these mule docs by the end of the day cannot create a tangible product. They marginally boost productivity. They are simply in place to track changes and bring structure to chaos. They inheritently do not provide performance improvements, fix bugs or add growth. If you focus is the later, you better to find an adaptive developer who can quickly grasp the code logic and work on bugs. Just make sure such devs efforts are recognised and are well paid.

Functional Design Documents (FDDs)

We so far discussed HLD's and LLD's, but there is a third type of doc called "FDD - short form for Functional Design Document"

These cannot be realistically referred as "Mule docs", because they barely contain information specific to Mule. However, they are the most important docs both for the business users and developers (especially the developers). The reason these docs are highly important is just for the fact that they alone contain pure information about the business requirement, such as "Why we are doing this?", "What is the scope?", "What are the business benifits?" etc.

Most developers I have witnessed ignore to read these docs, and in some projects they barely ask the `busines owners to prepare one`.

Yes, you read it right. These docs are "NOT TO BE PREPARED BY THE DEVELOPERS". These are meant to be prepared only by the Business/Functional owners. Its still so shocking how so many projects do this the wrong way.

Nevertheless, for a developer FDDs are really important, not because they add sense or give meaning to why an interface is being created, but most importantly, FDD act as a irrefutable contract stating:

What is asked?
What is delivered?

You see, business users simply cannot blame the devs for delivering the wrong product when they keep unofficially changing the requirements by the word of mouth, with forgettable directives. FDDs are safegaurding mechanisms for both the parties. If either party does anything different than what is specified, then they can be held accountable for it.

So the key thing here we must learn is to document everything. Always. Even if you don't like it and even if it does not give you tangible gains. FDD's are requested to be prepared by the Business owner and vendors must make it a standard practice.

If your project do not follow such standards, then convince people of its importance and how it makes everyones lives easy

Now lets see first the table of content of an FD in the next page

Table of contents of an Functional Design Document (FDD)

If you are a Functional/Business owner, then it is you who prepare the FD, not the Dev. If you are the Dev, then make sure to request the Functional owners for an FD in a similar format I show below.

Also, please note that the templates I share here are not universally followed. These things differ to a certain extent from client to client. Some clients have dedicated product teams who has Mule architects and devs, who would actually define the structure of these Mule docs. When a client has no idea how to prepare such docs, its your job as a vendor (assuming you are one) to provide you clients with the template. But again devs are NEVER meant to fill the FDDs. Let them worry about their own work.

Definitions

Now lets walk through the definitions of the above table of contents

Change History:

Contains the version, date, author, summary of changes for the version

Approver History:

Contains who approver which version from the above change history.

Interface ID:

Each MuleSoft interface (requirement) is identified by a unique ID. This helps in easy identification of the process area. Example, Mul-001, or I-001

Interface Description:

A high level description of what the interface does. In our scenario (which I showed in the very beginning), we could say "Payment Info from Bluebox Legacy API (fake name) to S/4"

Business team:

Specify the business team who needs this interface. Example: "Google - Finance Team". Where Google is our client name.

Business process area:

Specify the process area the business team is interested in. The Finance team can have serveral processed which needs to be integrated. Payment Info is one. AccountCashForecasts, Treasury bills, Invoices etc, are all process areas.

Release:

The clients product owner or project manager could decide which Release this will become a part of. Just know that serveral other team alongside with MuleSoft would be working to acheive a product (which is not just one Interface or an API). The product could be having several items or agendas. Example: R1 (Release 1)

Criticality of the interface (High, Low or Medium):

Define the Criticality of the interface High, Low or Medium so that devs or TLs could prioritise it. This actual specifies the Availability of the interface. If you say Criticality is High, then a lot of focus is needed in building the interface by having mechanisms which ensures the High Availability. Not all interfaces are equally important. Some interfaces need not run daily. They probably need to run once a week or a month. And even if that does not happen, the business have other means to rely on and so its not critical.

SLA based on Criticality:

This defines how quick any issues needs to be addressed by the Support. Typically, 8 hours is the SLA for High Criticality. 24 to 72 for Medium, 72 and above for Low.

Business requirement:

Specify a the business requirement on a high level but mostly from the business perspective and not mulesoft perspective. This can span multiple lines. Here you mention from where the source is getting the data. The categories of data. What happens once the data is received to the destination. Do we need full load, delta and adhoc load functionality etc

Business process flow (as a diagram):

This is self explanatory. Prepare a High level flow diagram of the business process from the business users perspective. Do not put mulesoft design flow diagrams in here. That is not what this is.

Business benifit:

Specify why this interface (aka integration) is needed and what use it could possibly have. Once again, all of this info doesn't have to make sense to a MuleSoft Dev who reads this. We are still talking from the perspective of the business and understanding the business.

If the developer is able to understand it all then it is an added bonus. Most of the time, MuleSoft devs only need technical info, like what is the source API endpoint, credentials, target endpoint and credentials. They will get to decide ultimately the MuleSoft Design. All of this business info is superficial to them. But it always helps to have these things documented.

In Scope and Out of Scope:

As a business owner here you mention what is in scope and what is out of scope for this intergration. This provide some insight (a hint) to the MuleSoft Dev what he or she could expect as a part of the interface.

You could also mention the potential integrations the dev could come across later a direct result of building this current integration

Dependencies:

Specify any functional or technical Dependencies that the Mule Dev must be aware of. This is critical for the dev to understand how to design and build the interface.

For example you could say, before the mulesoft development is complete, the other team namely S/4 development has to complete, because s/4 is the outbound for mulesoft. Similarly, you could mention things like Connections details are required for the Source Legacy API and the target S/4 API.

Functional and Technical constraints:

Here you mention all the functional constraints which could potentially hinder the work of the MuleSoft dev. But this is not always true. You could also mention,

Any source API file size or target limitations?
Whether pagination is availble or not?
How long the data will be retained in the source before MuleSoft processes it?
Whether source could potentially harbour duplicate records?
Is there any personally identifiable info (PII) is stored or transmitted from the source
Any special instructions for the Dev

Assumptions:

Specify all data, technical and integration assumptions here. For example:

What is the expected file size, and what is expected when the threshold is breached?
Uncertain rate limits due to lack of visibility
API responses stability and API stability
Any criterions or possibilities of parallel data executions on the source side which could cause undefined behaviour at MuleSoft
Whether sequential or parellel data processing is expected but not fully confident
Whether client credentials could potential update after a certain time period

Process flow diagram:

A simple flow diagram dipiciting the process similar to the business flow diagram. However, in here you need show where MuleSoft comes into the picture

Business logic and Relationships:

Just like the brief business requirement which talks about the business needs in just a few lines, this section must contain the detailed info on how the process needs to be implemented with MuleSoft in the view. It must contains all the Relationships between the processes and anything which needs to be conveyed to the reader.

Data sources:

As the name indicates, specify the interface data sources (could be one or multiple)

Transaction volume info (as a table):

Maintain a table showing the list of sources from which the data could come and the expected Daily, Monthly, Yearly volume all specified in JSON object count, ZIP, CSV, JSON or XML file sizes etc

Frequencies (as a table):

Maintain a table showing Full, Adhoc, Delta or Daily trigger timing and frequency

Data mapping (as a table or attachment):

Maintain a table with links and attachements showing what is the source to target mapping if present. Also maintain any sample file links here. Its better to have them as links than embedded attachments

Keep the mapping stupid and simple (following KISS principles). Have it readable and understandable. Devs do not care nor like to work with mappings which are written entirely from a business perspective with confusing jargon. Which is why its better to have mapping sheets prepared by Architects who understand the business terms and the technicalities. If not atleast have a dedicated session with the Dev, explaining the mapping prepared and how to interpret it.

Note: These mappings must never be requested to be prepared by a Developer because their focus is mostly on technicals, and delivering the product than understanding the inner workings of your business process. Dev does not need to know what "GLAccountingCashFlow and CashBalances statements" are to make their thing work.

Data retention requirement:

How long will you keep the data in the source or the target, before processing or after processing.

Potential issue or known issues and solutions (as a table):

Maintain a table showing the potential Error scenarios especially with different kinds of data. Like what happens when X data changes and how that needs to be handled? etc

Also mention why it needs to be handled in the Middleware layer instead of fixing it in the upstream itself? What is the rationale behind it?

Mention the cases when emails are to be expected and at what rate?

Mention what to do when the source breaks the contract by pushing too big files than expected

Procedure for Notification and Monitoring:

Explain in few lines what are steps to be taking to notify in case of errors. Specify what kind of errors you are expecting in an email and to whom exactly.

Mention the DL (email Distribution List or slack channel) specific to the environments

Testing requirements with scenarios (as a table):

If you have the test scenarios (success and failures) already prepared then specify them here. This must show what and which kinds of tests you will perform on the Interface once the SIT (System Integration Testing) commences

Security expectations and Audit:

Essentially in some projects where the business process areas which you are integrating for is financial/tax/treasury related which contains both PII and sensitive information, there are quality and compliance standards which MUST be followed and there are dedicated teams in the company which oversee such operations. So, it is must to inform the developers to not log payload and other things in code. This section elaborates on that.

I will finish the ID doc standards another time.

How MuleSoft API documentation works? (with template)