Skip to content
Thryv AEP

List

In REST APIs, it is customary to make a GET request to a resource collection’s URI (for example, /publishers/{publisherId}/books) in order to retrieve a list of the resources within that collection. Resource-oriented design AEP-121 honors this pattern through the List action.

Guidance

Section titled “Guidance”

APIs should provide a List action for resource collections. The purpose of the List action is to return data from a finite collection (generally singular unless the operation supports reading across collections).

When the GET HTTP method is used on a URI ending in a resource collection, the result must be a list of resources.

Operation

Section titled “Operation”

List operations must be made by sending a GET request to the resource collection’s URI path:

GET /v1/publishers/{publisherId}/books
  • The URI should contain a variable for each individual ID in the resource hierarchy.
    • The path parameter for all resource IDs must be in the form {resourceName}Id (such as bookId), and path parameters representing the ID of parent resources must end with Id.
  • List actions should implement sorting and filtering mechanisms to allow clients to sort and narrow results.

Requests

Section titled “Requests”
  • The HTTP method must be GET, and must follow the GET method guidelines in AEP-65.
    • The request must be safe and must not have side effects.
  • There must not be a request body.
    • If a GET request contains a body, the body must be ignored, and must not cause an error.
  • The request must not require any query parameters. 
paths:
  /publishers/{publisherId}/books:
    get:
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: query
          name: pageSize
          schema:
            type: integer
        - in: query
          name: pageToken
          schema:
            type: string

Responses

Section titled “Responses”

A List action must return 200 OK when resources are successfully retrieved.

The response must be paginated and follow these requirements:

  • The field results must be an array of resources, with the schema as a reference to the resource (e.g., #/components/schemas/Book).
  • Fields providing metadata about the List request (such as page tokens) must be included in the response wrapper object, not as part of the resource itself.
  • The response must ensure a deterministic default sort order to guarantee stable pagination.

If the collection exists but contains no resources, the response must return a 200 OK with an empty results array.

paths:
  /publishers/{publisherId}/books:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  nextPageToken:
                    type: string
                  results:
                    items:
                      $ref: '#/components/schemas/book'
                    type: array
                  unreachable:
                    items:
                      type: string
                    type: array
                type: object

Errors

Section titled “Errors”

A List action must return appropriate error responses. For additional guidance, see Errors and HTTP status codes.

Most common error scenarios:

  • Return 404 Not Found if the parent resource does not exist (e.g., requesting /publishers/{invalidId}/books when the publisher doesn’t exist).
  • See authorization checks for details on responses based on permissions.

Advanced operations

Section titled “Advanced operations”

List actions may allow an extended set of functionality to allow a user to specify the resources that are returned in a response.

The following table summarizes the applicable AEPs, ordered by the precedence of the operation on the results.

OperationAEP
filteringAEP-160
orderingAEP-132
paginationAEP-158

For example, if both a filter and pagination fields are specified, then the filter would be applied first, then the resulting set would be paginated.

Ordering

Section titled “Ordering”

List actions may allow clients to specify sorting order; if they do, the order must be specified in a query parameter which must be a string named orderBy.

  • Values must be the fields to sort by. For example: foo,bar.
  • The default sorting order is ascending. To specify descending order for a field, users append a - prefix; for example: foo,-bar, -foo,bar.
  • Subfields are specified with a . character, such as foo.bar or address.street.

Soft-deleted resources

Section titled “Soft-deleted resources”

Some APIs need to “soft-delete” resources, marking them as deleted or pending deletion (and optionally purging them later).

APIs that do this should not include deleted resources by default in list requests. APIs with soft deletion of a resource may include a boolean field named showDeleted in the list request that, if set, will cause soft-deleted resources to be included. For more information, see AEP-164.

Interface Definitions

Section titled “Interface Definitions”
paths:
  /publishers/{publisherId}/books:
    get:
      description: List method for book
      operationId: listBooks
      parameters:
        - in: path
          name: publisherId
          required: true
          schema:
            type: string
        - in: query
          name: pageSize
          schema:
            type: integer
        - in: query
          name: pageToken
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  nextPageToken:
                    type: string
                  results:
                    items:
                      $ref: '#/components/schemas/book'
                    type: array
                  unreachable:
                    items:
                      type: string
                    type: array
                type: object
          description: Successful response

Changelog

Section titled “Changelog”