Application boundaries that define APIs to invoke the application's business logic need to be made public to its clients, for example, other applications within the system. The question is, what information needs to be documented?

The application's bounded context is part of the context map. Therefore, the domain responsibilities should be clear. The application fulfills certain business use cases within its context.

This domain information needs to be documented first. Clients should be aware of what the application offers. This includes the use cases as well as the exchanged information and data ownership.

The responsibility of the car manufacture application is to assemble cars due to provided, exact specifications. The status information of manufactured cars is owned by the application for the whole process of assembling, until the car reaches the end of the production line and is ready for delivery. The application can be polled to provide status updates about the creation process of a car.

The application's domain description should contain the information the clients require, be precise in responsibilities, but not too verbose, only exposing what clients need to know.

Besides the business domain, there are technical aspects that need to be documented. Client applications need to be programmed against a system's API. They require information about the communication protocols, as well as data formats.

We covered several communication protocols and how to implement them in the second chapter of this book. At the time of writing, one of the most used protocols is HTTP, together with JSON or XML content types. With the example of HTTP, what needs to be documented?

HTTP endpoints, especially those following the REST constraints, represent the domain entities as resources, locatable by URLs. The available URLs need to be documented first. Clients will connect against these URLs in order to perform some business use cases. For example, the /car-manufacture/cars/<car-id> URL will refer to a particular car specified by its identifier.

The content type with detailed mapping information needs to be documented as well. Clients need to be aware of the structure and properties within the used content type.

For example, a car specification that is provided in order to create a car contains an identifier, an engine type, and a chassis color. The JSON format will look as follows:

{
    "identifier": "<car-identifier>",
    "engine-type": "<engine-type>",
    "color": "<chassis-color>"
}

The types and available values need to be documented as well. They will point to the business domain knowledge, the semantics behind an engine type. This is important, that both the content types as well as the semantics of the information are documented.

In the case of HTTP there will be more aspects to be documented such as potentially required header information, status codes provided by the web service, and so on.

All this documentation certainly depends on the used technology and communication protocol. The business domain, however, should also be part of the documentation, providing as much context as required.

The application's API documentation is part of the software project. It needs to be shipped together with the application in a particular version.

In order to ensure that the documentation matches the application's version, it should be part of the project repository, residing under version control as well. Therefore, it's highly advisable to use text-based documentation formats instead of binary formats such as Word documents. Lightweight markup languages such as AsciiDoc or Markdown have proven themselves well in the past.

The benefit of maintaining the documentation directly in the project, next to the application's sources, is to ensure the creation of documentation versions that are consistent with the developed service. Engineers are able to perform both changes in one step. Doing so prevents the documentation and service version from diverging.

There is a lot of tool support in documenting application boundaries depending on the communication technology. For HTTP web services for example, the OpenAPI Specification together with Swagger as a documentation framework are widely used. Swagger outputs the API definition as browsable HTML, making it easy for developers to identify the offered resources together with their usages.

Using Hypermedia REST services, however, gets rids of the biggest necessity of service documentation. Providing the information of which resources are available in links removes the need for documenting URLs. In fact, the server gets back the control of how URLs are constructed. Clients only enter an entry point, for example /car-manufacture/, and follow the provided Hypermedia links based on their relations. The knowledge what a car URL consists of solely resides on the server side and is explicitly not documented.

This is especially true for Hypermedia controls, not only directing the client to resources, but providing information on how to consume it. The car manufacture service that tells a client how to perform the create-car action: A POST request to /car-manufacture/cars is needed, including a request body in JSON content type with properties identifier, engine-type, and color.

The client needs to know the semantics of all relations and action names as well as the properties and where they originate. This is certainly client logic. All information on how to consume the API becomes part of the API. Designing REST services then eliminates the need for a lot of documentation.