페이지 매김, 필터링 및 API 버전 관리

Returning every record in one response is slow and memory-heavy. Pagination sends data in manageable pages.

The classic approach uses limit and offset driven by query params like ?page=2&per_page=20.

Clients need to know totals. Include metadata such as current page, page size, and total count alongside the data.

Large offsets get slow because the database still scans skipped rows, and rows shifting between requests cause duplicates.

Cursor pagination uses the last seen value (often an id or timestamp) to fetch the next page, staying fast and stable.

Let clients narrow results with query params. Build the query conditionally based on which params are present.

Reduce over a params map to apply each supported filter, keeping the query composable and safe from injection via parameter binding.

Accept a sort param and map it to a safe whitelist of allowed columns to avoid arbitrary ordering.

Versioning lets you evolve the API without breaking existing clients when you change response shapes or behavior.

The most common strategy puts the version in the path, scoped in the router.

Alternatively, select the version from an Accept header so URLs stay stable. Choose ONE strategy and stay consistent.

You made APIs scalable and durable:

• Paginate with offset (simple) or cursor (fast, stable)
• Return page metadata with the data
• Apply composable, parameter-bound filters and whitelisted sorting
• Version via URL path or Accept header, consistently