10 Designing user-friendly and interoperable operations flows

Operations flows are the sequences of API calls consumers perform to achieve a use case, and making them user-friendly and interoperable requires more than good individual operations. The chapter emphasizes treating flows as cohesive wholes that are concise, flexible, helpful, and consistent. Designers should minimize steps, avoid forcing a rigid call order, and prevent avoidable errors or heavy output-to-input data processing. Consistency and standardization across similar flows (and with widely used patterns such as HTTP uniform interface, predictable paths, and common security flows) make APIs guessable, reusable, and easier to integrate. Crucially, flow optimization comes after improving data and individual operations, ensuring the building blocks are already user-friendly and interoperable.

To optimize flows, the chapter recommends removing redundant calls, adding use-case-focused features or operations when they fit the subject matter, aggregating operations prudently, and including ready-to-use output data that reduces client-side computation and error risk. The money transfer example shows how moving from generic lists and trial-and-error validation to targeted operations and enriched responses (e.g., valid source–destination pairings and acceptable amount ranges) shortens the flow and reduces failure. It also stresses flexibility: enabling multiple valid entry points and avoiding UI constraints by, for instance, offering operations that let clients gather source, destination, and amount in any order—while guarding against over-aggregation or leaking provider-centric details into consumer-facing designs.

For data-saving flows, the chapter promotes partial, order-independent saving with minimal vital data captured early, allowing applications to build the UI that suits their context and to resume work reliably. It suggests consolidating updates around a central resource when it aligns with the domain, separating validation from completion, and embedding status and guidance (e.g., “complete” vs. “incomplete” plus messages) with each save so clients always know what’s missing without treating incompleteness as an error. Finally, it recommends supporting both one-shot and multi-step flows (via flags or distinct resources) and cleanly switching from partial to final resources using standard HTTP mechanisms. Together, these practices produce concise, error-limiting, and flexible flows that minimize friction for developers and deliver smoother end-user experiences.

We enhance the "Renting a car" operations flow by reducing the number of steps, avoiding constraining the order of operations, creating use case-focused operations, and preventing error and data processing.

We optimize operations flows after reworking data and operations to make them user-friendly and interoperable.

The money transfer use case or operations flow has some issues we can fix.

We can remove calls returning data already retrieved.

We add a transfer-related filter on List accounts to get only transfer-eligible accounts.

We add the "List destinations for source" use-case-specific operation to avoid processing data of the generic "List accounts" and "List beneficiaries" operations.

We add ready-to-use amount ranges when listing destinations to avoid consumers calculating them and limit the risk of an "Amount not in acceptable range" error when calling "Transfer money."

Optimized money transfer flow lacks flexibility, which can be fixed by adding new or aggregated operations.

The operations flow to open a current account comprises several data-saving steps constraining consumer flow. We can fix that.

By enabling partial creation and completing data with update operations for subscription, services, agency, card, and holder information, we allow consumers to build a UI flow matching their needs.

We merge all add/update operations of sub-elements (services, banking cards, holders) into the Update subscription operation.

FAQ