Mike's Notes
- Use this template, which is available on GitHub.
- Credit both Chris & Matt.
- It closely matches what I use anyway, but it is much better laid out.
- Most of these metadata fields are already completed.
- The existing project documentation generator could quickly work with this template to batch output HTML and PDF files.
- Pipi will not be using Saga's; however, it can work with workflow messaging.
Resources
- https://microservices.io/post/microservices/general/2019/02/27/microservice-canvas.html
- https://github.com/cer/microservice-canvas
References
- Reference
Repository
- Home > Ajabbi Research > Library >
- Home > Handbook >
Last Updated
11/05/2025
Documenting a service using the microservice canvas
In What’s a service—part 1? I described the key aspects of a service, including its API and dependencies. A good way to document a service and its structure is to use a microservice canvas. A microservice canvas is a concise description of a service. It’s similar to a CRC card that’s sometimes used in object-oriented design.
I first read about the canvas in a 2017 DZone article by Matt McLarty and Irakli Nadareishvili. I’ve since adapted its structure so that it emphasises the interface (top of the canvas) and the dependencies (bottom of the canvas) and de-emphasises implementation (middle of the canvas).
Here is an example of a microservice canvas. It describes the Order Service, which is part of my book’s example FTGO application.
A service’s external view
The service’s external view is described by the following sections:
- Name - name of the service
- Description - a brief description of the service
- Capabilities - the business capabilities implemented by the service
- Service API - the operations implemented by the service and the domain events published by the service
- Quality attributes - the service’s quality attributes, which are also known as non-functional attributes
- Observability - includes health check endpoint, key metrics, etc.
A service’s dependencies
A service’s dependencies are described by the dependencies section, which consists of two parts.- Invokes - the operations which are implemented by other services that this service invokes
- Subscribes - the messages, which include events, that this service subscribes to
A service’s implementation
The canvas can also describe the service’s implementation, such as its domain model.
Example canvas
- Take a look at the example canvas.
To learn more
- My book Microservices patterns
- The FTGO application, which is my book’s example application
