9 Designing user-friendly and interoperable operations

Designing operations that are both user-friendly and interoperable reduces development friction, limits bugs, and improves end-user experiences. This chapter explains how to make operations immediately understandable and guessable, flexible enough to fit varied use cases, and predictable across an entire API surface. It emphasizes meeting real needs with clear, visible capabilities, leveraging user-friendly data, and aiming for consistency and standardization so that developers can rely on familiar patterns and behavior everywhere.

Concretely, operations should express capabilities through meaningful, hierarchical, and predictable resource paths combined with standard HTTP methods, using globally unique identifiers to keep paths short without losing accuracy. Inputs must be easy to provide by choosing HTTP-compliant locations (path, query, headers, body), mapping inputs to outputs, preferring well-known or standard identifiers and formats, and minimizing required fields via sensible defaults or server-derived values when appropriate. Successful responses should be ready to use: return appropriate status codes and place data where developers expect it, favoring complete resource models when creating or updating. List and search endpoints should offer optional filtering, sorting, and pagination with helpful defaults and clearly returned metadata, while data adaptation can be achieved through content negotiation (formats and locale) and cautious, purpose-driven tweaks via query parameters.

Error handling is treated as a first-class design concern: limit errors by accepting reasonable input variants, use appropriate and familiar status codes, and return feedback that is both human-friendly and machine-readable, exhaustive, and actionable—optionally leveraging standardized problem formats. The chapter also warns against hiding multiple capabilities in do-it-all operations, encouraging designers to revisit granularity and purpose so each operation is clear. Finally, it calls for consistent, standardized data, features, and behaviors across operations (identifiers, response shapes, creation semantics, feature availability), producing APIs that are guessable, flexible, and dependable—making integration faster and safer for developers.

Once we have designed versatile operations that do the job, we can revisit them to ensure they’re user-friendly and interoperable. We’ll rework HTTP representations and input and output data modeling.

Consistent and interoperable user-friendly operations with appropriate granularity, HTTP representation, input, output, and helpful error handling are easily used by anyone and any system.

We question needs and leverage globally unique IDs to reduce the number of path parameters in the Banking API resources paths and make them easier to use.

Choosing user-friendly input data locations in an HTTP request depends on HTTP and common practice. Choosing appropriate locations facilitates the providing and understanding of input data.

Creating a money transfer requires input data to be put in the body to be HTTP-compliant and user-friendly.

Using a path parameter for the account identifier and query parameters for the transactions resource modifiers makes the List account transactions operation user-friendly.

We minimize money transfer inputs by determining data based on other data and using default data.

Better return the transaction complete model when listing an account’s transactions so developers have everything they need and don’t need to call Read transaction for each one.

Enabling filtering, sorting, and paginating lists is essential to allow consumers to get only the elements they need sorted as needed.

The pagination, sort, and filter metadata lets consumers know exactly what they get (especially when default parameter values are used) and if there are other available elements.

Content negotiation allows consumers to request an account’s transactions in different formats by sending a standard Accept header.

It is possible to transfer money with a JSON or XML input and get a response in JSON or XML regardless of input format

Money transfer machine-readable errors returned when sending unsupported data format or currency make it easy to show errors in UI.

The Money transfer operation performs all possible checks and returns an exhaustive list of errors, which avoids annoying back-and-forth.

An error response of the Money transfer operation leveraging and customizing the Problem Details for HTTP APIs standard

FAQ