Cursor rule

1---
2description:
3globs: **/*.{openapi.yaml}
4alwaysApply: false
5---
6headers:
7  - name: Link
8    type: standard
9    direction: response
10    required: optional
11    description: Contains HATEOAS navigation links for previous, next, first, and last pages.
12 
13  - name: Cache-Control
14    type: standard
15    direction: response
16    required: optional
17    description: Defines cache policies for paginated endpoints. Must align with page token expiration (e.g., `max-age=900`).
18 
19query:
20  - name: page_size
21    type: uint32
22    default: 20
23    max: 100
24    required: optional
25    description: Number of items per page. Requests above max must return validation error.
26 
27  - name: page_token
28    type: string
29    required: optional
30    description: Opaque token that identifies the current page. Must be treated as opaque and server-controlled.
31 
32  - name: order_by
33    type: string
34    default: created_at
35    allowed: [created_at, updated_at, reference_at]
36    required: optional
37    description: Defines the field used for sorting. Any other value must result in a 400 error.
38 
39  - name: sort
40    type: string
41    default: asc
42    allowed: [asc, desc]
43    required: optional
44    description: Defines sorting direction. Must reject other values with appropriate error.
45 
46response:
47  - name: data
48    type: array
49    description: List of items for the current page. Must follow the resource structure of the endpoint.
50 
51  - name: pagination.page_size
52    type: uint32
53    description: Number of items returned in the current page.
54 
55  - name: pagination.total_count
56    type: uint32
57    optional: true
58    description: Total number of records for the original query. May be omitted to optimize performance.
59 
60  - name: pagination.next_page_token
61    type: string
62    optional: true
63    description: Token for retrieving the next page. Null or absent when no next page exists.
64 
65  - name: pagination.previous_page_token
66    type: string
67    optional: true
68    description: Token for retrieving the previous page. Null or absent when this is the first page.
69 
70  - name: pagination.first_page_token
71    type: string
72    optional: true
73    description: Token representing the first page in the dataset. Useful for restarting navigation.
74 
75  - name: pagination.last_page_token
76    type: string
77    optional: true
78    description: Token for jumping to the last page. Optional for optimization.
79 
80rules:
81  - if: no page_token is provided
82    then: return first page using default sort and page_size
83 
84  - if: page_size exceeds 100
85    then: return 400 Bad Request with reason PAGE_SIZE_TOO_LARGE
86 
87  - if: order_by contains invalid values
88    then: return 400 Bad Request with reason ORDER_BY_INVALID
89 
90  - if: sort contains invalid values
91    then: return 400 Bad Request with reason SORT_INVALID
92 
93  - if: page_token is invalid
94    then: return 400 Bad Request with reason PAGE_TOKEN_INVALID
95 
96  - if: page_token is expired
97    then: return 400 Bad Request with reason PAGE_TOKEN_EXPIRED
98 
99  - if: no results found
100    then: return 200 OK with empty data array and pagination.total_count = 0
101 
102  - enforce: All tokens must be opaque, signed or encrypted, and expire after 10 minutes
103 
104  - log: Every paginated request must include X-Grd-Trace-Id for audit and observability
105 
106notes:
107  - Pagination must be documented in OpenAPI contracts.
108  - Pagination must be implemented even for endpoints expected to return one item.
109  - Tokens must not be reused beyond their expiration.
110  - All pagination behaviors must be stateless and deterministic.
111  - Clients must not rely on token structure or decoding.
112