IPA-124: Repeated Fields

Providing clients with lists of data can be complex. Aligning on a single strategy for providing clients with repeated fields allows the complexity to be reduced when clients need to modify the lists.

Guidance

• Repeated fields must use a plural field name
• Repeated fields should have an enforced upper bound that will not cause a single resource payload to become too large
  • A good rule of thumb is 100 elements
  • If repeated data has the chance of being too large, the API should use a sub-resource instead
• Client-owned repeated fields should be respected by the server
  • The server should not modify the order of elements or remove duplicates, without explicit documentation that the server will do so

Update Strategy

• A resource may use one of two strategies to enable updating a repeated field:
  • Direct update using the standard Update method
    • A standard Update method is only able to update the entire list
  • Custom Add and Remove methods
    • When choosing a custom method approach, API consumers must not be able to set the field via Create or Update operations

note

Declarative-friendly resources must use the standard Update method, and not introduce Add and Remove methods. To learn more, see IPA-127.