Singleton sub-resource

As explained in API Design Patterns

A singleton sub-resource is an API sub-resource representing one distinct related entity rather than a collection of entities.

A singleton sub-resource is a hybrid of a resource and a property: it stores data inherent to a parent resource in a separate, independently addressable location. Use it when the data is large, complex, highly restricted, or changes at a different rate. section 12.0 section 12.2

Apply the standard methods with these constraints:

• Get and update the singleton like a separate resource; address it with its own identifier, such as drivers/1/location. section 12.3.1
• Create it automatically when the parent is created; require no separate initialization method. section 12.3.1
• Delete it automatically with the parent; do not expose ordinary create or delete operations for the singleton. section 12.3.1 section 12.6
• Allow only one instance and consider a custom reset operation for restoring default attributes. section 12.4.2 section 12.6

Driver location

A Driver resource can keep slowly changing metadata such as a license plate while exposing frequently changing location data as a singleton sub-resource. Clients retrieve or partially update it through the location endpoint, while creating the driver creates the location automatically. section 12.1.1 section 12.3.1

Figure 12.1 Resource moving the location property to a Location singleton sub-resource

Visualizes moving a location property from a resource into a Location singleton sub-resource. section 12.2

How API Design Patterns covers it

How deep it goes

Defines the hybrid model, explains lifecycle and method semantics, and stops short of implementation-specific storage details.

Examples

Uses driver location, employee compensation, license plates, ACLs, and resource-method comparison tables and figures.

What it assumes

Assumes parent resources and standard API methods while teaching the singleton’s hybrid behavior and lifecycle from first principles.

What you can do after

Evaluate when to split a property and design its address, update, creation, deletion, and reset behavior.

How it connects

Connects resource properties, parent resources, subcollections, access control, volatility, and partial replacement.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

• cascading deleteused by · Cascading delete is the automatic propagation of a parent-record or resource deletion to associated dependent records or resources.
• HTTP GETuses · HTTP GET is a request method for retrieving a representation of a resource identified by the request target, without requesting a state change.
• database updateuses · A database update is an operation that modifies existing records, rows, documents, or other stored data according to specified criteria.
• parent elementpart of · A parent element is an entity directly above another entity in a hierarchy, with the latter being its child.
• resourcecontrasts with · An API resource is a conceptual entity or target exposed through an interface and addressable for access or manipulation.

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.