From d088b0b23fe6f06478d877a977442d309ba2c0e6 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Fri, 14 Aug 2026 17:01:29 +0200 Subject: [PATCH] docs(api): drop the first and last pagination links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The API no longer advertises `rel="first"` or `rel="last"`. `first` was a duplicate of calling the endpoint with no cursor, and `last` was not the final page of a forward walk but a backward walk from the end of the dataset — so it landed on a page boundary that paging forward never produces. Documenting them sent readers toward links that either told them nothing new or returned items shifted against every other page. Also documents that `next` and `prev` each appear only when there is somewhere to go, so a response with nothing before or after it carries no `Link` header at all, and points readers at the cursor-less request as the way back to the first page. Engine change: Mergifyio/monorepo#38724 Related to MRGFY-3192 Change-Id: Id80e1c8ba52f12978f8761755d1e5a8be208676a --- src/content/docs/api/usage.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/api/usage.mdx b/src/content/docs/api/usage.mdx index 7a8a832992..376ed8a3ac 100644 --- a/src/content/docs/api/usage.mdx +++ b/src/content/docs/api/usage.mdx @@ -146,20 +146,23 @@ for navigating between pages. **Link header example:** ```http -Link: ; rel="next", - ; rel="last", - ; rel="first" +Link: //logs?cursor=abc&per_page=20>; rel="next", + //logs?cursor=def&per_page=20>; rel="prev" ``` The `Link` header may include the following relations: - `next`: The next page of results - `prev`: The previous page of results -- `first`: The first page of results -- `last`: The last page of results + +Each relation appears only when that page exists: `next` is absent on the last +page, `prev` on the first. The two are independent, and a middle page carries +both. When neither applies — a result set that fits on a single page — the +`Link` header is omitted entirely. To iterate through all pages, follow the `rel="next"` link -until it is no longer present in the response. +until it is no longer present in the response. To get back to the first page, +call the endpoint again without a `cursor`. ## Error Handling