IPA-105: List

In many APIs, it is customary to make a GET request to a collection's URI (for example, /groups/{groupId}/clusters) to retrieve a list of resources, each of which lives within that collection.

State

Adopt

Guidance

• APIs must provide a List method for resources unless the resource is a singleton
  • The purpose of the List method is to return data from a finite collection
• The HTTP verb must be GET
• The method must not cause side effects
• The request must not include a body
• The response body should consist of the same resource object returned by the Get method
  • The object may include any HATEOAS links field from the individual resource
• The response status code must be 200 OK

Example

GET /groups/${groupId}/clusters

Naming

• Operation ID must be unique
• Operation ID must be in camelCase
• Operation ID must start with the verb “list”
• Operation ID should be followed by a noun or compound noun
• The noun(s) in the Operation ID should be the collection identifiers from the resource identifier in singular form, where the last noun is in plural form

Examples:

Resource Identifier	Operation ID
/groups/${groupId}/clusters	listGroupClusters

Further Reading

• IPA-110: Pagination