Offset-based pagination

Access paginated data via an offset into the total dataset.

Offset-based pagination allows API consumers to configure the exact range of results to return.

Pros

Straightforward to implement for relational databases, as it maps one-to-one with SQL OFFSET and LIMIT clauses.
Supports random access to data.
Easier to support different sort or filter options.

Cons

Does not
If new data is added or removed from the dataset the data is still being retrieved, the results may become inconsistent.
Poor abstraction making it difficult to migrate database structures later.

Usage

Paginated APIs support two optional query parameters, offset and limit.

Parameter	Description
`offset`	The starting point from which to return results. The first result has an offset of 0. Default is 0.
`limit`	The maximum number of results to return. Default is 100.

Not specifying any parameters returns the first page of results:

Default request

curl https://api.example.com/records

An offset can be specified to return subsequent pages of results.

With offset specified

curl https://api.example.com/records?offset=2

Implementation notes

It is a good idea to enforce an upper limit for the limit parameter, to prevent consumers from exhausting your server's resources.

OpenAPI reference

{
  "openapi": "3.1.0",
  "info": {
    "title": "Offset-Based Pagination Example API",
    "version": "1.0.0"
  },
  "paths": {
    "/records": {
      "get": {
        "summary": "list all records",
        "parameters": [
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "Offset": {
        "name": "offset",
        "in": "query",
        "description": "The starting point from which to return results. The first result has an offset of 0. Default is 0.",
        "required": false,
        "schema": {
          "type": "number",
          "minimum": 0,
          "default": 0
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "The maximum number of results to return. Default is 100.",
        "required": false,
        "schema": {
          "type": "number",
          "minimum": 1,
          "maximum": 100,
          "default": 100
        }
      }
    }
  }
}