From 8b7a7ede320f60e9a72ecfee9876ad373ec7797a Mon Sep 17 00:00:00 2001 From: Kamil Ciula Date: Wed, 14 Oct 2026 14:05:37 +0200 Subject: [PATCH 1/2] feat(openapi): describe nextPage and previousPage as page paths List responses return `page.nextPage` and `page.previousPage` as the path of the adjacent page, relative to the server URL, so a client can request it directly. The path keeps the query parameters of the request and carries the cursor in `after` or `before`, which the API still accepts. Co-Authored-By: Claude Opus 5.5 --- openapi/components/parameters/After.yaml | 5 ++++- openapi/components/parameters/Before.yaml | 6 ++++-- openapi/components/schemas/Page.yaml | 14 ++++++++++---- 3 files changed, 18 insertions(+), 7 deletions(-) diff --git a/openapi/components/parameters/After.yaml b/openapi/components/parameters/After.yaml index 202bf01..8d8a8dc 100644 --- a/openapi/components/parameters/After.yaml +++ b/openapi/components/parameters/After.yaml @@ -1,6 +1,9 @@ name: after in: query required: false -description: Use the `nextPage` value as the `after` parameter to get the next page. +description: |- + Cursor of the next page. + `page.nextPage` contains it as the `after` query parameter, so you can also request `page.nextPage` directly. + The cursor is opaque, and its internal structure is subject to change. schema: type: string diff --git a/openapi/components/parameters/Before.yaml b/openapi/components/parameters/Before.yaml index b244d53..28bc13b 100644 --- a/openapi/components/parameters/Before.yaml +++ b/openapi/components/parameters/Before.yaml @@ -1,7 +1,9 @@ name: before in: query required: false -description: | - Use the `previousPage` value as the `before` parameter to get the previous page. +description: |- + Cursor of the previous page. + `page.previousPage` contains it as the `before` query parameter, so you can also request `page.previousPage` directly. + The cursor is opaque, and its internal structure is subject to change. schema: type: string diff --git a/openapi/components/schemas/Page.yaml b/openapi/components/schemas/Page.yaml index 76bd73a..74e4aa2 100644 --- a/openapi/components/schemas/Page.yaml +++ b/openapi/components/schemas/Page.yaml @@ -4,18 +4,24 @@ properties: type: - string - 'null' + format: uri-reference description: |- - Use with the `after` query parameter to load the next page of data. + Path of the next page, relative to the API server URL. + Append the value to the server URL to get the next page. + The path keeps the query parameters of the request and sets `after` to the cursor of the next page. When `null`, there is no next page. - The cursor is opaque and internal structure is subject to change. + example: /menu?limit=10&after=G0EAAIyUqm8V previousPage: type: - string - 'null' + format: uri-reference description: |- - Use with the `before` query parameter to load the previous page of data. + Path of the previous page, relative to the API server URL. + Append the value to the server URL to get the previous page. + The path keeps the query parameters of the request and sets `before` to the cursor of the previous page. When `null`, there is no previous page. - The cursor is opaque and internal structure is subject to change. + example: /menu?limit=10&before=G0EAAIyUqm8W limit: type: integer minimum: 1 From 7af43fbc6e9ebc0e8722c18c69f508d05d5077d5 Mon Sep 17 00:00:00 2001 From: Kamil Ciula Date: Thu, 15 Oct 2026 10:32:31 +0200 Subject: [PATCH 2/2] feat(openapi): add the 1.1.0 changelog entry and use schema examples for page paths `example` is deprecated on a Schema Object in OpenAPI 3.2, so the page path examples use the JSON Schema `examples` list. The changed meaning of `nextPage` and `previousPage` is listed under 1.1.0. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 +++++++++ openapi/cafe.yaml | 2 +- openapi/components/schemas/Page.yaml | 6 ++++-- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 01e30f3..39a3a6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 1.1.0 (2026-10-15) + +### Changed + +- `page.nextPage` and `page.previousPage` in list responses (`GET /menu`, `GET /orders`) are now the path of the adjacent page, relative to the server URL, for example `/menu?limit=10&after=G0EAAIyUqm8V`. + The path keeps the query parameters of the request. + Request it directly instead of passing the value as the `after` or `before` parameter. + The `after` and `before` parameters still accept a cursor, which is the value of that parameter in the path. + ## 1.0.1 (2026-10-14) ### Changed diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index 6685235..f026c35 100644 --- a/openapi/cafe.yaml +++ b/openapi/cafe.yaml @@ -4,7 +4,7 @@ info: description: | Demo API for cafe operators (not customers) to manage menus, orders, and revenue. Create API credentials and try it yourself in a realistic OpenAPI workflow. - version: 1.0.1 + version: 1.1.0 contact: email: team@redocly.com url: https://redocly.com/contact-us/ diff --git a/openapi/components/schemas/Page.yaml b/openapi/components/schemas/Page.yaml index 74e4aa2..e9433cc 100644 --- a/openapi/components/schemas/Page.yaml +++ b/openapi/components/schemas/Page.yaml @@ -10,7 +10,8 @@ properties: Append the value to the server URL to get the next page. The path keeps the query parameters of the request and sets `after` to the cursor of the next page. When `null`, there is no next page. - example: /menu?limit=10&after=G0EAAIyUqm8V + examples: + - /menu?limit=10&after=G0EAAIyUqm8V previousPage: type: - string @@ -21,7 +22,8 @@ properties: Append the value to the server URL to get the previous page. The path keeps the query parameters of the request and sets `before` to the cursor of the previous page. When `null`, there is no previous page. - example: /menu?limit=10&before=G0EAAIyUqm8W + examples: + - /menu?limit=10&before=G0EAAIyUqm8W limit: type: integer minimum: 1