[ADP-312] 分頁
reviewing phase 1
更正 OpenAPI 範例
概述
RESTful API 中的分頁是一種將大型數據集分割成更小、更易管理的塊或"頁面"的技術。這有助於提高性能、減少服務器負載並提供更好的用戶體驗。
分頁主要有兩種方法：基於偏移的分頁和基於游標的分頁。
基於偏移的分頁
基於偏移的分頁使用偏移值來指定數據集的起始點，並使用限制來指定要檢索的項目數。
示例
http
GET /resources?offset=20&limit=10 HTTP/1.1http
{
"resources": [ /* 從偏移量20到29的資源 */ ],
"meta": {
"offset": 20,
"limit": 10,
"totalItems": 100
},
"links": {
"self": "/resources?offset=20&limit=10",
"next": "/resources?offset=30&limit=10",
"prev": "/resources?offset=10&limit=10",
"first": "/resources?offset=0&limit=10",
"last": "/resources?offset=90&limit=10"
}
}WARNING
此處使用 HATEOAS 提供上下頁連結，但是 HATEOAS 在本指導原則中並不推薦使用。
基於游標的分頁
基於游標的分頁使用游標(通常是唯一標識符)來獲取下一組結果。
示例
http
GET /resources?cursor=abc123&limit=10 HTTP/1.1http
{
"data": [ /* 從游標abc123之後開始的資源 */ ],
"meta": {
"next_cursor": "def456",
"limit": 10
},
"links": {
"self": "/resources?cursor=abc123&limit=10",
"next": "/resources?cursor=def456&limit=10"
}
}WARNING
此處使用 HATEOAS 提供上下頁連結，但是 HATEOAS 在本指導原則中並不推薦使用。
指導原則
應該(SHOULD)選擇分頁約定並使用常見的查詢參數進行分頁。目前基於游標的分頁更為常見。
應該(SHOULD)使用常見的查詢參數(query parameters)來做分頁，即：
cursor,offset,limit。應該(SHOULD)在回應標頭中提供下一頁/上一頁的鏈接，詳情參見ADP-145: Link。
httpLink: <https://api.example.com/resources?cursor=test123>; rel="next", <https://api.example.com/resources?cursor=test123>; rel="prev",
示例
OpenAPI 示例
http
openapi: 3.1.0
info:
title: 示例 API
version: 1.0.0
paths:
/resources:
get:
summary: 獲取資源列表
parameters:
- name: page
in: query
description: 分頁的頁碼
required: false
schema:
type: integer
- name: filter
in: query
description: 過濾條件
required: false
schema:
type: string
- name: sort
in: query
description: 排序順序
required: false
schema:
type: string
responses:
'200':
description: 分頁的資源列表
headers:
Link:
description: 分頁鏈接
schema:
type: string
content:
application/json:
schema:
type: object
properties:
resources:
type: array
items:
type: object
total:
type: integer
page:
type: integer
pageSize:
type: integer