Solution

Teams must publish the Trilateral API of each of their components. This not only includes documenting the APIs, but also understanding that published interfaces, when they are changed, must be backwards compatible. To this end, all APIs must have consume-driven contract tests. We will discuss contract testing in Chapter 7, Testing. Teams must understand the implications of their choice of deployment options. We will discuss these topics in Chapter 6, Deployment.

Document the event stream topology of the system. For each stream, document its purpose and any guidelines for producers and consumers. Provide a diagram of the stream topology with at least the major components included. Document the base event type envelope format that all events must conform with, as was discussed in the Event Streaming pattern. Events are typically formatted as JSON documents. As such, it is a good idea to document event types using TypeScript interface syntax, regardless of what language is used by producers and consumers.

Each team should create a diagram for each of its components, similar to the one discussed earlier, that identifies all the internal resources of the component. Document all the APIs of each component and make the documentation part of each component's git repository so that it is easily accessible by all teams. Use the preferred specification tool, such as Swagger, Raml, or GraphQL, for the synchronous API. For the asynchronous APIs, document all the event types that are produced and/or consumed, as TypeScript interfaces. Document the consumed events from the consumer perspective, to highlight the fields that the consumer depends on. For produced events, include all the available context information in the event.

It is impossible to predict what information future consumers might need, so it is more flexible to include additional information than to not have the necessary information. Events are a record of history, thus context information is an important part of understanding an event. Do not go out of the way to retrieve additional information, but do not exclude information that is readily available. Downstream components can adorn additional information as necessary, but they should not have to re-retrieve information that was present at the time of the event. In many cases, the consumer will actually want to work with a snapshot of the data at the time of the event.