In this series, we’ve explored drawing boundaries around software parts. We’ve discussed integration patterns, forming new relationships between decoupled parts. This week, we explore creating structure for the “sources” of information in a decoupled system. Specifically, how APIs can communicate information in a well-structured way.
Sources of information have layers; the software part itself, the logic that governs communication, the specific digital locations where communication happens (endpoints) and the information being shared. The layers that interface with consumers and govern communication with the application, are the API (application programming interface).
Designing these layers will likely be familiar. Even tightly-coupled software (usually) interfaces with other software or resources. Software that serves web pages, for example, is a source of information, with an endpoint (URL) that serves it (to a browser) based on logical rules.
Sharing information depends, to some extent, on when that information is needed. When a customer buys a product, the software part handling the transaction might want to find out, from another software part, if the customer has a credit that can be applied. When a news article is updated, readers need to see the edited version. In some situations, a consumer checks the source for new information every 24 hours. In others, consumers send bazillions of asynchronous requests.
We will dive into timing (events) in subsequent weeks. In another edition, we’ll discuss streaming information and events. Here, we’ll specifically look at APIs as the interface to share and retrieve information.
In its simplest form, an API enables one software part to get information from another software part. As complexity in a system increases, APIs become integrated into the architecture, essential to the system’s design. Kubernetes, for example, makes extensive use of APIs to orchestrate interactions across a complex series of services.
APIs can retrieve information from many types of storage; databases, S3, file systems, as well as operating systems, services running in the cloud, etc. They can be local or remote, using different types of protocols (HTTP, RPC). They can structure responses using XML, JSON or … there isn’t a limiting rule about the structure of responses except that ideally, they are useful and appropriate for the consumer. APIs that return HTML, for example, aren’t helpful to consumers that aren’t displaying web pages.
The emerging practice of Hypermedia APIs generates responses that are dynamic and discoverable. Instead of getting the static information, consumers get links to endpoints where further, deeper information is available. The consumer’s logic dictates which links to follow. A query language like GraphQL can sit on top of an API so consumers can ask for exactly what they want, across multiple API endpoints, and omit information they don’t need. The more sophisticated our digital systems become, the more avenues of communication design open up.
Here are some resources to explore APIs. As always, we’d love to hear any recommendations you have!
“It seems we’ve got a mental block when it comes to hypermedia in web APIs. This is a big problem, because hypermedia is the feature that makes a web API capable of handling changes gracefully.”— Leonard Richardson