Documenting APIs

Business Platforms are characterized by a system context that includes multiple integration points (APIs) with different systems. In complex solutions, the number of integration points increases, and an effective way to document them becomes critical for the program's success.

I will focus here on some key aspects to effectively design, implement, maintain, and reuse platform APIs, such as:

• Choosing a Design Strategy
• Choosing an explicit Target Focus for the documentation
• Handling consistently multiple types of APIs, including both synchronous and asynchronous ones

API Design Strategy

The first key design choice is the strategy for defining the APIs. Two common strategies exist:

• Code First: Operations and data are defined by developers directly in code, with API specifications and further documentation generated via annotations (e.g. with JAX-RS in Java), either exposing documentation endpoints when deployed or generating specification files during the build process. This approach delegates API stability responsibility to developers and is often better suited to internal APIs between closely related agile teams that allow for great amounts of flexibility.  
• Contract First: The API specification is designed first, typically using some kind of modeling technique (e.g. Domain Driven Design - DDD, see also). This allows parallelization of work between API producers and consumers, which will integrate at the end of the development phase.  This approach works best for external APIs and requires effective planning and change control to manage it effectively to guarantee both consistency and a sufficient amount of flexibility in API definition.

A large-scale business platform will use a combination of both approaches but will be mostly characterized by its external APIs that benefit the most from a contract-first approach.

Documentation Target Focus

Another key design choice is to balance the target focus of the API documentation, balancing the following two aspects

• Human-Readable: describing the context and scope of the API, and how to use it, with different levels of complexity covered through examples and tutorials.
• Machine-Readable: enabling several capabilities such as formal version tracking via source control repositories, automated generation of client/server code for different implementation languages, and automated validation of message payloads.

Having formal, machine-readable documentation is a must to manage APIs at scale in a large Business Platform. Most API Gateway solutions provide capabilities to publish this kind of documentation, together with additional human-readable documentation to authorized consumers. Additionally, they provide and document consistent security capabilities to manage the authorization keys and secrets to integrate APIs in production environments.      

Handling multiple API Types  

API Types can be broadly split into two main categories:

• Synchronous:  based on Request/Reply interaction pattern. Examples of this type of API  are SOAP over HTTP,  REST or GraphQL
• Asynchronous:  based on message sending with a Publish/Subscribe interaction pattern. Single or multiple subscribers are possible. Examples of this type are Kafka, AMQ, JMS messaging, use of Websockets or Web Services with asynchronous bindings (e.g. SOAP over JMS)  

Each technology has its own technical features that are reflected in the API specification but also define Business-specific data. Service components might be composed of both synchronous and asynchronous operations that need to operate on a common domain model (eventually defined using approaches like Domain-Driven Design - DDD).  

OpenAPI and AsyncAPI provide this level of compatibility, by allowing the use of JSON Schema references to specify the business-specific data (Request, Response, Messages).  Common Schema definitions can then be shared across multiple APIs of different kinds that participate in business processes using the same entities.  

Other technologies can also use this pattern, such as:

• Both synchronous and asynchronous web services can use WSDL and XSD specification formats
• GraphQL schemas as extensions/combinations of multiple JSON schemas

Conclusion

AsyncAPI and OpenAPI are now both part of the Linux Foundation, so both are well-supported and have a stable future as open standards with community governance and are becoming more and more integrated with open-source tooling and commercial products providing API Gateways features, such as IBM API Connect.