中文
devexamples
← Workflows

阅读中文版本

API Pagination Standardization Workflow

Choose one pagination style across the API, define cursor or page semantics, document limits and errors, and migrate inconsistent endpoints gradually.

intermediate~90 minapidesignconsistency

Objective

Make pagination consistent across endpoints so clients have one mental model and one implementation.

Environment

  • An API with multiple list endpoints
  • A place to document the convention

Steps

1. Choose a primary style (cursor

Choose a primary style (cursor or page) and a default and max page size.

Expected state: The convention is fixed.

2. Define response shape, next-cursor semantics,

Define response shape, next-cursor semantics, and end-of-list signals.

Expected state: Clients know how to iterate.

3. Standardize error responses for invalid

Standardize error responses for invalid or expired cursors.

Expected state: Failures are predictable.

4. Migrate inconsistent endpoints gradually with deprecation

Migrate inconsistent endpoints gradually with deprecation.

Expected state: Old clients are not broken abruptly.

Decision points

Cursor or page numbers?

  • Cursor
  • Page

Cursor for feeds and large data; page numbers when users need to jump.

Silent clamp or error on oversized page?

  • Error
  • Clamp silently

Return an error for oversized requests; silent clamping hides client bugs and skews expectations.

Expected outcome

A single documented pagination convention applied across list endpoints, with a migration path for the outliers.

Verification

Confirm new endpoints follow the convention, the limits are enforced, and invalid cursor errors are consistent.

Cleanup

Publish the pagination guide and track endpoints still to migrate.

Overview

Make pagination consistent across endpoints so clients have one mental model and one implementation. Confirm new endpoints follow the convention, the limits are enforced, and invalid cursor errors are consistent.

Steps

  1. Choose a primary style (cursor or page) and a default and max page size. Expected state: The convention is fixed.
  2. Define response shape, next-cursor semantics, and end-of-list signals. Expected state: Clients know how to iterate.
  3. Standardize error responses for invalid or expired cursors. Expected state: Failures are predictable.
  4. Migrate inconsistent endpoints gradually with deprecation. Expected state: Old clients are not broken abruptly.
{
  "data": [ /* items */ ],
  "meta": { "nextCursor": "eyJpZCI6MTAwfQ", "limit": 20 }
}

Verification

  • A single documented pagination convention applied across list endpoints, with a migration path for the outliers.

Decision points

  • Cursor or page numbers? Options: Cursor; Page. Recommended: Cursor for feeds and large data; page numbers when users need to jump.
  • Silent clamp or error on oversized page? Options: Error; Clamp silently. Recommended: Return an error for oversized requests; silent clamping hides client bugs and skews expectations.