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.

Guidance

1. 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

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   The collection /groups/{groupId}/clusters exposes a GET List method, so callers can retrieve the finite set of clusters within the group.

   1. For each collection URI in paths (a path ending in a collection noun with no trailing resource identifier), check whether the resource is a singleton. Singletons are exempt.

   2. Confirm the collection URI defines a get operation.

   3. If a non-singleton collection has no get operation, flag the missing List method.

2. The HTTP verb must be GET.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   The List method is defined under the get verb on the collection URI.

3. The method must not cause side effects.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters
         responses:
           "200":
             description: OK

   Why:

   The List operation only reads and returns the collection; it does not create, modify, or delete any resource.

   1. Inspect the get operation on the collection URI and review its description and behavior.

   2. Confirm the operation only reads data and does not mutate server state.

   3. If the operation creates, updates, or deletes resources, flag it as causing side effects.

4. The request must not include a body.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters
         parameters:
           - name: groupId
             in: path
             required: true
             schema:
               type: string

   Why:

   The List operation defines no requestBody; all input is supplied through path and query parameters.

5. 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

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters
         responses:
           "200":
             content:
               application/json:
                 schema:
                   type: object
                   properties:
                     results:
                       type: array
                       items:
                         $ref: "#/components/schemas/ClusterResponse"
     /groups/{groupId}/clusters/{clusterName}:
       get:
         operationId: getGroupCluster
         responses:
           "200":
             content:
               application/json:
                 schema:
                   $ref: "#/components/schemas/ClusterResponse"

   Why:

   The List response reuses the same ClusterResponse object returned by the Get method, so a single resource has one consistent shape across both methods.

   1. Locate the resource schema returned by the Get method for the same resource.

   2. Compare it to the object type returned in the List method's response array.

   3. If the List method returns a different object shape, flag the divergence.

6. The response status code must be 200 OK.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters
         responses:
           "200":
             description: OK

   Why:

   The successful List response is declared with the 200 status code.

Example

GET /groups/${groupId}/clusters

Naming

1. Lint rule ↗

   Operation ID must be unique.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters
     /groups/{groupId}/users:
       get:
         operationId: listGroupUsers

   Why:

   Each operation has a distinct operationId, so no two operations collide.

2. Lint rule ↗

   Operation ID must be in camelCase.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   listGroupClusters starts with a lowercase letter and capitalizes each subsequent word, following camelCase.

3. Lint rule ↗

   Operation ID must start with the verb "list".

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   The operationId begins with the verb list, identifying the operation as a List method.

4. Operation ID should be followed by a noun or compound noun.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   The verb list is followed by the compound noun GroupClusters, naming what is listed.

5. 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.

   paths:
     /groups/{groupId}/clusters:
       get:
         operationId: listGroupClusters

   Why:

   For /groups/{groupId}/clusters, the collection identifiers are groups and clusters; the leading noun is singularized to Group and the final noun stays plural as Clusters, giving listGroupClusters.

   1. Extract the collection identifiers from the resource URI in order, ignoring path parameters.

   2. Singularize each collection identifier except the last, which stays plural, and concatenate them in camelCase after the list verb.

   3. Compare the result to the actual operationId; if they differ, flag the naming mismatch.

Examples:

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

Further Reading

• IPA-110: Pagination