This chapter emphasizes that user-friendly, interoperable APIs must be designed as coherent wholes, not just as collections of well-designed parts. It cautions against monolithic, vaguely named “everything” interfaces that hinder discovery, understanding, and consistent usage. The guidance focuses on giving each API a clear, focused purpose; helping developers find and grasp it quickly; and, where useful, enabling runtime discovery and navigation with standard HTTP features and optional hypermedia.
To determine granularity, analyze optimized flows and group independent sets of operations into one or several APIs. Sub-domains can be split yet remain connected through interoperable identifiers, and a single application may expose multiple APIs; when in doubt, start with one and split later. Names are critical for comprehension and evolution: choose concise, domain- or use-case-centered names and avoid generic, project-based, or meaningless labels. To aid routing and recognition, include the API name in the base path used by all resources.
For interoperable browsing, rely on standard mechanisms: use the OPTIONS method to surface allowed actions on a resource, and the Link header for pagination, alternate representations, and related resources. When beneficial, offer hypermedia formats such as HAL or Siren via content negotiation alongside plain JSON to describe relations and available actions. Keep essential subject-matter data in the payload (not only in metadata), and add browsing capabilities only when they deliver clear value—especially for dynamic or AI-driven clients—since these features can be introduced incrementally over time.
We’re almost done with the user-friendly and interoperable API design layer.
According to SMEs and confirmed by our analysis of the operations flows, the Banking API comprises three independent sets of operations (Account Information, Money Transfer, and Subscription).
Using the OPTIONS HTTP method allows consumers to know which operations are available on a resource.
We can provide formats, pagination, and links to other resources with the Link header when listing transactions or reading a transfer.
HAL and Siren propose standardized representations of links between resources. Siren adds the description of possible actions and separates original data and hypermedia metadata.
FAQ
What makes an API user-friendly and interoperable at the API level?A user-friendly, interoperable API has a clear, focused purpose; it builds on consistently designed data, operations, and flows; and it can help consumers discover relations and actions at runtime by correctly leveraging HTTP and, optionally, hypermedia metadata.How do I decide between building one API or multiple APIs?Analyze operations and their flows to spot heterogeneous or independent areas. If a set of operations can be used without the others (e.g., separate sub-domains like account information, money transfers, and subscriptions), split them into distinct APIs. Also consider separating business vs. monitoring/security concerns.When in the process should I finalize API granularity?Decide after you’ve optimized data, operations, and flows, because that’s when you see the real capabilities and boundaries. If unsure, start with one API and split later; consumers typically need only small configuration changes (like a base path) when you do.How can I identify independent sets of operations that suggest multiple APIs?Use SME input and examine operations flows. If a flow for one goal never requires operations from another area, it’s a candidate sub-API. Diagramming operations connected by flows makes these clusters visible and justifies the split.Can related sub-APIs interoperate without tight coupling?Yes. Share interoperable identifiers (for example, standardized account IDs) and acknowledge bounded contexts. The same business concept can appear as different resources across sub-APIs, linked by common IDs, allowing independent use and optional cross-API navigation.How should I name an API, and what should I avoid?Use plain, meaningful names tied to the domain, concept, or use case (e.g., “Money Transfer,” “Account”). Avoid generic (“API”), project- or time-bound (“New Banking Architecture”), or purely whimsical names. Ensure the name matches the actual capabilities to set clear expectations.Should the API name appear in the base path?Yes, adding the name to the base path (e.g., /account, /transfer) helps users and gateways identify and route to the right API. In OpenAPI, set servers[0].url to the API’s base path. Versioning can also live in or alongside the base path as needed.How can clients discover allowed operations on a resource at runtime?Use the HTTP OPTIONS method. Respond with an Allow header listing supported methods for the current resource state (e.g., GET, DELETE), enabling clients to know whether actions like update or delete are currently possible.How do I advertise pagination, alternate formats, and related resources?Use the Link response header (RFC 8288). Provide rel=prev/next for pagination; rel=alternate with type for other formats (e.g., CSV, PDF); and add links to related resources (e.g., source and destination of a transfer) so clients don’t have to guess URLs.What are hypermedia APIs (HATEOAS), and when should I adopt them?Hypermedia APIs embed standard metadata that describe relations and actions (e.g., HAL, JSON:API, Siren, JSON-LD). Benefits: runtime discoverability, easier generic or AI-driven clients, smoother evolution. Offer them via content negotiation (e.g., Accept: application/hal+json); advertise supported formats with Link. Keep essential subject-matter facts (like IDs or a cancellable flag) in the payload so the API remains usable even if clients ignore hypermedia.
pro $24.99 per month
access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
The Design of Web APIs, Second Edition ebook for free
