[ADP-310] Collection Semantics

INFO

This ADP provides an overview of collection semantics for RESTful APIs.

Guidelines

• Collections SHOULD be represented using plural nouns in URIs.
• Collection resources SHOULD support pagination, filtering, and sorting.
• Collection responses SHOULD include metadata about the collection (e.g. total count, pagination links).
• Individual resource representations within a collection SHOULD be consistent with their standalone representations.

Collection Operations

Retrieving Collections

• Use GET to retrieve a collection of resources.
• Support query parameters for pagination, filtering, and sorting.

Example:

GET /users?page=2&per_page=100&sort=name HTTP/1.1

Creating Resources in Collections

• Use POST to create a new resource in a collection.
• Return the created resource representation and a 201 Created status code.

Example:

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Bulk Operations

• Consider supporting bulk create, update, or delete operations for collections.
• Use a consistent format for bulk operation requests and responses.

Example bulk create:

POST /users/bulk HTTP/1.1
Content-Type: application/json

{
  "users": [
    { "name": "User 1", "email": "user1@example.com" },
    { "name": "User 2", "email": "user2@example.com" }
  ]
}

Related ADPs

• ADP-312: Pagination
• ADP-313: Filtering
• ADP-314: Sorting

Reference

Design Reference

• https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/