When considering the practice of API design, many focus on the technical elements: HTTP methods such as GET and POST, JSON payload structures, and path design. Yet, there is much more to the process of API design than those technical elements. API design is rooted in communication. This article explores the the idea of communication in API design by looking at three areas: the marketplace, consuming developers, and network boundaries.
Communication with the marketplace
The design of an API and its associated documentation informs prospective customers, partners, and internal developers what outcomes the APIs make possible through the digital capabilities they offer. Effective API design helps to communicate these digital capabilities, empowering others to use them directly or build upon them.
To understand digital capabilities, we must first understand business capabilities. Business capabilities describe the enablers an organisation brings to market. Examples of business capabilities include consumer product design, product manufacturing, and customer support.
Digital capabilities are assets that turn desired outcomes into reality by producing digital outcomes. Examples include REST APIs, Webhook-based asynchronous APIs for integration, SOAP services, and message streams.
When you think of API design, it is important to understand the digital capabilities that the API offers. These capabilities should become part of your API documentation, enabling business leaders as well as developers to understand the value an API provides. Some organisations find it useful to map the digital capabilities of each API back to their business architecture to trace their value streams.
Interestingly, communication can work both ways. Organisations reviewing the digital capabilities offered by a competitor’s product or service provides greater insights into what that organisation values. It can even be extended to view the market segments addressed.
When evaluating an API design, consider the digital capabilities offered. Ask someone outside the design team to tell you what your value stream and market segments appear to be. You may be surprised at what your API design communicates that you didn’t intend.
Additional resources:
- What makes a great developer portal for your API?
- What’s the minimum documentation required for an API?
Communication with consuming developers
When developers think of software design, thoughts of classes, methods, functions, modules, and databases likely spring to mind. UML sequence diagrams or “box and arrow” diagrams are used to convey understanding across a solution. All these elements are part of the communication process development teams use for understanding and future developer onboarding.
Likewise, API design is a communication process for developers. The API documentation is the user interface for developers. It informs developers what operations are available, along with how and when they are able to use them. This forms the foundation of most API reference documentation, captured using the OpenAPI Specification.
Yet, unless an API’s operations are designed to be used in a standalone manner, the documentation requires more than just a reference of each operation. API documentation must convey how its operations are able to be combined to achieve more complex results. If an API design forgets to factor these elements into its design and documentation effort, developers will be confused and require additional support to be successful. Worst case, they may choose to try a different API or build it themselves – perhaps out of pure frustration.
Communicate with your target audience early and often during the API design process is essential to meet the needs of developers consuming the API. Going the extra distance to fully document an API’s usage, not just the details of each operation, will help them solve problems quickly.
Additional resources:
- Great API documentation requires code examples
- 10 essentials when creating an Open API specification
Communication Across Network Boundaries
An API’s design, including its choice of protocol, has an impact on the chattiness of the API. Network protocols, such as HTTP, are better for coarse-grained communication. GraphQL supports response shaping, which is a way that the client communicates its needs to the server. Other protocols such as gRPC, MQTT, and AMQP are better suited for fine-grained communication within a defined network boundary.
The API design reflects the frequency of communication between systems and the impact it may have on performance due to network boundaries and bottlenecks. The API design process has a heavy impact on performance of the client and server.
Select an API style that ensures that systems can communicate at the level of granularity desired. A thoughtful API design process helps us to consider these aspects of network-based communication during the design phase to ensure the right API style(s) are available for developers.
Additional resources:
How does your API communicate?
Remember the three dimensions of API design communication: the marketplace, consumers, and network boundaries. Then, ensure that what you have designed effectively communicates across these three dimensions when considering your API design. If necessary, revisit your API design and its associated documentation to ensure that you are communicating on all levels.
