Response format

The representation of a collection MUST be an object containing a field with the same plural resource name appearing in the collection's URL. This field MUST contain an array of resources in the collection. This response object MAY also include collection metadata, such as for pagination.^[1]

{
  "accounts": [
    {
      "id": "499aed3c-3f49-4a04-8e69-44c2f2894195",
      "company_name": "Aperture Science",
      "href": "https://api.example.com/v2/accounts/499aed3c-3f49-4a04-8e69-44c2f2894195"
    },
    {
      "id": "2f27ff7b-3183-4e9a-a085-db457402ee95",
      "company_name": "Black Mesa",
      "href": "https://api.example.com/v2/accounts/2f27ff7b-3183-4e9a-a085-db457402ee95"
    }
  ]
}

Non-canonical collection URLs

A resource has only one canonical location (also known as its permanent location), which is reflected in its href property. By extension, a resource has only one canonical collection, such as /v2/accounts in the example above. However, relationships with other resources may warrant adding non-canonical collections. Consider a conference speaker scenario, where PUT /v1/conferences/{conference_id}/speakers/{id} is used to add a speaker to a conference. In this case, /v1/conferences and /v1/speakers are the canonical collections for conferences and speakers respectively. In contrast, /v1/conferences/{conference_id}/speakers is the non-canonical collection listing the speakers for a given conference.

Since non-canonical collections are intended to list associations between resource types, and access to those resource types may require different authorizatons, the representation of the collection SHOULD return reference schemas rather than canonical or summary schemas.

{
  "speakers": [
    {
      "id": "1ed3d170-5cd7-466e-8c11-787d0228809f",
      "name": "brian-kernighan",
      "href": "https://api.example.com/v1/speakers/1ed3d170-5cd7-466e-8c11-787d0228809f"
    },
    {
      "id": "fa25c029-d7b9-4348-805b-8bd3b5eed8f2",
      "name": "vint-cerf",
      "href": "https://api.example.com/v1/speakers/fa25c029-d7b9-4348-805b-8bd3b5eed8f2"
    }
  ]
}

Wildcard collection URLs

To facilitate reading resources across collections, one or more path parameters in a collection's request URL MAY be wildcarded with the - (hyphen or dash) character. For example, GET /v1/farms/-/barns requests all barns, regardless of the farm.

Wildcards MUST be limited to collection GET methods, which may only support wildcards for path parameters. Path parameters that support wildcards MUST be explicitly documented. Wildcard support MUST NOT affect any pagination, filtering, and sorting support otherwise provided by a collection method. The sorting requirement means wildcards MUST NOT be used if duplicate resources could be returned, or if not all sort options can be supported.

Individual resource URLs

Resources belonging to a collection MAY be individually addressable, and if so, their URLs SHOULD start with the URL of the collection.^[2] For example, an account in the /v2/accounts collection would have the URL /v2/accounts/:account_id where :account_id is the unique account identifier.

Each individual resource's canonical URL SHOULD be included in the root of its representation as the href property. This URL SHOULD be complete and begin with the protocol (e.g., https://api.example.com/v2/accounts/499aed3c-3f49-4a04-8e69-44c2f2894195). The wildcard character ( -) MUST NOT appear in the property value (i.e., canonical parent identifiers MUST be used).

Wildcard individual URLs

As a convenience for clients, resource URLs that include parent resource identifiers but are uniquely identified^[3] by the final identifier MAY allow clients to wildcard any parent resource identifiers with the - (hyphen or dash) character (e.g. GET /v1/farms/-/barns/dc0eff9d-5a8c-46b9-9553-e1a0e554caaf). The final identifier MUST NOT be wildcarded, and any path parameters that support wildcards MUST be explicitly documented. The server MUST NOT return the resource, but instead return 301 Moved with a resolved code