[Schema Inaccuracy] Should GET /user/repos be paginated?

[tonyarnold]

Schema Inaccuracy

GET /user/repos does not include pagination information in the returned header responses, despite taking page/per_page in the query.

Expected

The response should include headers containing the standard set of links to the previous, next, first and last pages.

I've found that if I manually add these to the schema I'm using that this endpoint does return the expected pagination details.

[calvinchilds]

Thanks for your report @tonyarnold ! Could you clarify what you mean by

I've found that if I manually add these to the schema I'm using that this endpoint does return the expected pagination details.

that is, what schema and what did you add to make the pagination details show up when they weren't before?

[tonyarnold]

Hi @calvinchilds - no worries at all!

I have tried both the JSON and the YAML schema, but I found if I located the section for /user/repos, and added the following under the existing content block, the Link properties come through in the response:

headers:
    Link: *37

[calvinchilds]

Thanks for replying! What are you plugging that schema into i.e. what are you using to call the API, is it a client library, CLI, curl?

[tonyarnold]

I'm generating Swift sources using Apple's Swift OpenAPI Generator, and compiling them into a desktop app that I've been building for monitoring workflow changes on my Mac.

[calvinchilds]

I tried this with curl -I "https://api.github.com/user/repos" and found the link header which looked like

link: <https://api.github.com/user/repos?page=2>; rel="next", <https://api.github.com/user/repos?page=35>; rel="last"

and did not show up for my other account with few repositories (as the documentation mentions).

I'm not familiar with Swift OpenAPI Generator - is the purpose of that configuration to allow certain headers through? Does the same thing happen with other GitHub API endpoints?

[tonyarnold]

I tried this with curl -I "https://api.github.com/user/repos" and found the link header […]

The issue I'm trying to report here is that the Link header is not in the Open API spec that's been published for api.github.com for this endpoint, so it's not being decoded by tooling that uses the spec to generate code around this.

I'm not familiar with Swift OpenAPI Generator […]

From the repository:

"Generate Swift client and server code from an OpenAPI document."

"Swift OpenAPI Generator is a Swift package plugin that can generate the ceremony code required to make API calls, or implement API servers."

[calvinchilds]

Ah I think I get you now. In https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml search for repos/list-for-authenticated-user and the responses section doesn't have

headers:
    Link:
        "$ref": "#/components/headers/link"

as some others do. I imagine this is the issue - we'll get on this 👍 (and this is something we should more actively check against our API documentation)

[tonyarnold]

That's exactly the issue. Sorry I wasn't able to be clearer in explaining it.

[calvinchilds]

No worries, glad we got there in the end 😄