Documenting API Governance
How do you document the processes behind API governance?
It's easy to document API definitions, style guides, linting rules, lifecycle transitions, and many other governance-related artifacts. What's not so simple is to document the interactions between API governance stakeholders. Yes, you can try to use workflow diagrams, but that feels complicated. Or, you can textually describe every single interaction, but that feels overwhelming. I believe I found a method that's already been proven to work in other areas. Tag along as I explore it.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
API governance is a service. It's a service that you—or your team—provide to other companies or teams. You have a group of people on one side helping another group of people manage their APIs in a better way. Some of the outputs of API governance are tangible. Artifacts like linting rules and style guides are important because they're evidence that the API is being governed. However, they don't inform API governance participants on how they should engage in the process or what steps they should follow. Since API governance is a service, I thought of using an appropriate documentation method, instead of "reinventing the wheel."
Service design is a discipline that applies existing and proven design processes to the creation—and improvement—of services. I'm not going to detail all the characteristics of service design here. Instead, I want to pay particular attention to one of the tools people use when doing service design: the service blueprint. It's a diagram that uses a single view to put together the perspectives of all the different stakeholders of a service. Service blueprints can detail things like the interactions between the different participants, the pieces of evidence of each interaction, the things that happen behind the scenes, and also the ones that are visible to the people who requested the service, who, in many cases represent the customer.
It feels like service blueprints can be an interesting way to document API governance processes, so I'm giving it a try. But, what does a service blueprint even look like? And, what information should I put on it? To learn how it works let's create a blueprint for a hypothetical API governance service (let's simplify the example by giving more focus to API review elements). Most service blueprints have five lanes: evidence, customer journey, front stage, backstage, and support processes. The goal of the evidence lane is to show all the artifacts that are left behind each step of the process. An example of an artifact is an API review report. The customer journey lane focuses on all the steps the stakeholder takes during the API governance process. The front stage lane shows the actions the API governance teams perform that are visible to the stakeholders. The backstage lane records all the API governance team actions that are hidden from the stakeholders. Finally, the support processes lane deals with all the elements that help the API governance team with its duties. Altogether these different lanes provide all the information you need to understand how an API governance process works.
Let's start by creating a simplified list of the evidence items related to an API governance process:
API governance kick-off: a meeting between you and the stakeholder—or the respective teams—where the stakeholder shares the current state of their APIs, and you explain the scope of your work.
List of APIs and related artifacts: a document defining all the APIs owned by the stakeholder and any related artifacts. The document should include pointers to the full documentation of each API, a sample of known consumers, and observability data.
API review checklist: a list of the things you want to check during an API review activity, including adherence to existing linting rules, correct usage of common data types, and existing good practices.
API governance report: a report with information related to the APIs of the stakeholder, including the quality of the APIs, API reviews, and consumer interview notes
Recommended actions: a list of recommended follow-up actions, like making changes to the API description, adopting different data types, and improving the documentation.
Now, let's work on the second lane, the customer journey. Let's define a customer action for each evidence item identified before where the stakeholder has direct participation:
Discusses current needs during the API governance kick-off.
Shares list of APIs and related artifacts.
Discusses results of API reviews while examining the API governance report.
Plans follow-up actions according to the recommendations.
Finally, let's identify the actions the API governance team takes for each identified evidence:
Introduces API governance during kick-off.
Requests list of APIs and related artifacts.
Prioritizes APIs that should be reviewed first.
Reviews each API following the checklist.
Documents the aggregate result of the reviews in the API governance report.
Shares the report with the stakeholder.
Recommends improvements from a list of actions from the report.
It's clear that your API governance service blueprint can be different from this one. After all, there are specific details that only you know about. However, you can use this blueprint as a basis for documenting any of your API governance processes. Give it a try and you will see how much your knowledge of API governance will improve.