docs(api): drop the first and last pagination links - #12394
Open
jd wants to merge 1 commit into
Open
Conversation
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
Contributor
Merge Protections🔴 2 of 6 protections blocking · waiting on 👀 reviews
🔴 👀 Review RequirementsWaiting for
This rule is failing.
🔴 🔎 ReviewsWaiting for
This rule is failing.
Show 4 satisfied protections🟢 🤖 Continuous Integration
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
Updates the public API pagination documentation to match current behavior by removing rel="first" and rel="last" from the described Link header relations, and clarifying how clients should navigate back to the beginning of a cursor-based listing.
Changes:
- Removes documentation for
rel="first"/rel="last"and updates theLinkheader example accordingly. - Documents that
next/prevlinks are only present when applicable, and that returning to the first page is done by omittingcursor.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
149
to
+150
| Link: <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=abc&per_page=20>; rel="next", | ||
| <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=xyz&per_page=20>; rel="last", | ||
| <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=def&per_page=20>; rel="first" | ||
| <https://api.mergify.com/v1/repos/Mergifyio/my-repo/logs?cursor=def&per_page=20>; rel="prev" |
Comment on lines
+158
to
+159
| Either relation is present only when there is a page to go to, so a response | ||
| with nothing before or after it carries no `Link` header at all. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The API no longer advertises
rel="first"orrel="last".firstwas a duplicate of calling the endpoint with no cursor, andlastwas not the final page of a forward walk but a backward walk fromthe 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
nextandpreveach appear only when there issomewhere to go, so a response with nothing before or after it carries
no
Linkheader at all, and points readers at the cursor-less requestas the way back to the first page.
Engine change: Mergifyio/monorepo#38724
Related to MRGFY-3192