A list is an ordered collection of values addressed by position with square brackets, such as items[2]. It may contain strings, numbers, maps, or nested lists, and commonly represents primitive values inherent to an API resource. section 5.6
Book categories
A Book resource can expose categories as a list of strings: categories: string[]. This keeps simple, intrinsic category data in the resource while presenting an interface useful to remote users, regardless of database storage. section 5.6
Design list fields with explicit ownership and limits:
- Treat the entire list as one atomic value: replace it as a whole rather than exposing updates to individual positions. section 5.6.1
- Provide one authoritative update path; separate endpoints for replacing a list and editing its items can create consistency surprises. section 5.6.1
- Bound both the total item count and each item’s size, and reject inputs beyond those limits instead of truncating them. section 5.6.2
- Use a subcollection when growth is difficult to bound; pagination can help manage an already large resource. section 5.6.2
- Prefer an empty list as a genuine value, and avoid using it ambiguously to request a default. section 5.6.3
Listing 5.7 Storing a list of categories on a Book resource
interface Book {
id: string;
title: string;
categories: string[]; #1
}
Shows a concise resource shape for storing a list of category strings on a Book. section 5.6
When an empty list cannot be distinguished from a default request, use a creation-time default only when empty is invalid; otherwise model the data as a separately managed subcollection. section 5.6.3
