5 Modeling data

This chapter explains how to turn previously identified API operations and their HTTP representations into clear, consumer-friendly data models. It advocates modeling all data exchanged via HTTP—path and query parameters, headers, and bodies—using JSON’s portable types for broad interoperability. The goal is a versatile API that meets needs without exposing inner workings, achieved by carefully selecting names, types, structures, and required fields, while postponing debates on fine details until later design layers address usability, performance, security, and implementation constraints.

The method starts with designing complete theoretical resource models that capture all relevant concept data and identifiers, then deriving them into operation-specific inputs and outputs. Typical patterns streamline this work: complete, summarized, minimal, and identifier models for outputs and routing; creation, replacement, and modification models for inputs—excluding server-managed fields and adjusting required flags by context. CRUD operations follow consistent recipes (e.g., read returns the complete model, search uses summaries and aligned filters, create may return minimal data plus Location, update distinguishes PUT replacement from PATCH modification), and a simple provisional error model keeps outputs exhaustive. The same approach extends to “Do” operations, either by creating business concept resources (executions/results) or using action resources with clear input/output models.

Finally, the chapter shows how data models reveal gaps and sharpen focus: tracing input sources and output usages helps spot missing capabilities (such as lookup resources needed to supply valid inputs), and refining inputs uncovers complete business error cases. Designers must differentiate similarly named concepts across contexts, ensure consistency and clarity in naming and typing, and guard against leaking provider structures or overfitting to a single consumer or UI. The result is a coherent, future-proof set of models that are easy to use, exhaustive enough for implementation and testing, and adaptable across use cases.

Once we have represented operations with HTTP, including choosing data locations in HTTP requests and responses, we can work on data modeling.

We’ll model the data of the resources of the Online Shopping example.

We’ll model the data of the input and output of the Online Shopping example’s operations

We model all HTTP request and response data (path parameters, query parameters, headers, and bodies).

The data we model is the data exchanged between the consumer and the provider; it may differ from the underlying data stored in the database.

To ensure all consumers can understand our data, we use the JSON portable data format. It handles Boolean, number, string, array, and object data types.

We leverage theoretical resource models to design inputs and outputs. We ensure that data meets needs without exposing inner workings; we especially check input sources for gaps in capabilities.

The Catalog contains many products; it is an array. The product is an object.

The Product resource theoretical model contains all the information necessary to describe a product in the context of the API.

The operation output is the Product resource model; required properties are always returned. The productReference path parameter is based on the productReference property.

The product summary model is a subset of the product model containing essential information describing a product in the context of a list.

To model the data participating in product creation, we start with the complete model and remove the data managed by the server.

The model for PUT matches product creation. Modifying two properties requires sending all data. The model for PATCH is similar, but all properties are optional; consumers send only modified data.

To be exhaustive on output data modeling, we design a simplistic and generic error model that we will enhance later.

The typical API operations leverage typical data models.

Starting from the complete data model, we can design summarized (essential information), minimal (only the resource identifier property, and identifier (only the resource identifier value) models.)

Starting from the complete model, we can design the creation, replacement, and modification input data models that contain only consumer-managed data.

FAQ