A repeated field holds multiple values or items of the same conceptual field, such as a list of strings or nested interfaces. In a web API, addressing an item by array index is usually misleading: indexes are unstable identifiers and imply a durable ordering. section 8.3.3
Prefer stable identity when repeated items must be addressed:
- Use a map field when items need stable, locally unique identifiers. section 8.3.3
- Use a collection of sub-resources when each item needs its own globally unique identifier. section 8.3.3
- Avoid designing partial updates around positions unless the resource is immutable or the index is genuinely unique. section 8.3.3
Listing 8.5 Representation of a ChatRoom with multiple administrators
interface ChatRoom {
id: string;
title: string;
description: string;
administrators: User[]; #1
}
interface User {
name: string;
email: string;
// ...
}
Shows a repeated nested interface through a ChatRoom resource with multiple administrators. section 8.3.3
Listing 8.6 A (bad) example of attempting to update items in a repeated field by index
PATCH /chatRooms/1?fieldMask=administrators.*.name HTTP/1.1
Content-Type: application/json
{
"administrators": [
{ "name": "New name for Index 0" }, #1
{ "name": "New name for Index 1" }
]
}
Illustrates a problematic PATCH that attempts to update administrators by array index. section 8.3.3
