docs wrongly indicate baptiste preview is functional on repo list endpoints

[ahmadnassri]

I'm re-opening this ticket as this is a docs issue, not a support issue.

the apis simply do not operate as described in the docs.

the endpoints: GET /users/{username}/repos and GET /orgs/{org}/repos both do not respond with the template_repository in the real world.

Proof

Testing that the correct Accept header is used:

expected result: null values for is_template

http https://api.github.com/users/ahmadnassri/repos?per_page=100 "Authorization: token $GH_TOKEN" | jq .[].is_template

expected result: some repos will return true, the rest are false

This Works

http https://api.github.com/users/ahmadnassri/repos?per_page=100 "Authorization: token $GH_TOKEN" "Accept: application/vnd.github.baptiste-preview+json" | jq .[].is_template

so, now that we can confirm we're making the correct API calls, and setting the correct headers, now lets try to look for template_repository property:

here's an example you can run yourself, using httpie and jq

http https://api.github.com/users/ahmadnassri/repos?per_page=100 "Authorization: token $GH_TOKEN" "Accept: application/vnd.github.baptiste-preview+json" | jq '.[] | { name: .name, should_have_template_repository: .name | startswith("js-"), template_repository: .template_repository, should_have_is_template: .name | startswith("template-"), is_template: .is_template }'

this is relying on the naming schema I strictly follow for my repos, specifically, repos that start with template- are template repositories, and for the purpose of this test, repos that start with js- are repositories that were initialized with a template repository, and the GitHub UI correctly reflects this, however it's not present in the API.

I've run this on my own public repos, and anybody can see those same results, as well as on private orgs, so both documentation for orgs and users are wrong.

here are the results:

{
  "name": "js-restful-core",
  "should_have_template_repository": true,
  "template_repository": null,
  "should_have_is_template": false,
  "is_template": false
}
{
  "name": "js-restful-json",
  "should_have_template_repository": true,
  "template_repository": null,
  "should_have_is_template": false,
  "is_template": false
}
{
  "name": "js-restful-node",
  "should_have_template_repository": true,
  "template_repository": null,
  "should_have_is_template": false,
  "is_template": false
}
{
  "name": "js-restful-request",
  "should_have_template_repository": true,
  "template_repository": null,
  "should_have_is_template": false,
  "is_template": false
}
{
  "name": "js-restful-xhr",
  "should_have_template_repository": true,
  "template_repository": null,
  "should_have_is_template": false,
  "is_template": false
}
{
  "name": "template-docker",
  "should_have_template_repository": false,
  "template_repository": null,
  "should_have_is_template": true,
  "is_template": true
}
{
  "name": "template-js-lib",
  "should_have_template_repository": false,
  "template_repository": null,
  "should_have_is_template": true,
  "is_template": true
}
{
  "name": "template-node-lib",
  "should_have_template_repository": false,
  "template_repository": null,
  "should_have_is_template": true,
  "is_template": true
}
{
  "name": "template-template",
  "should_have_template_repository": false,
  "template_repository": null,
  "should_have_is_template": true,
  "is_template": true
}

The Issue

The docs clearly show the wrong example for listing user repos:

and again with listing org repos:

The API in the real world does not provide these functionality, so the documentation is wrong.

if you believe the API should be providing this functionality, then perhaps that's an internal discussion for your team ... asking me to contact customer support and report an issue is not the appropriate path, you're advertising capabilities in your API through the docs that do not exist... so the first place is to fix the docs so they are reflective of what is actually available ..

once that's done, we the users of your platform, would have a better understanding of what's available and what is functional, instead of doubting our sanity and wasting hours of in debugging our own work, because the docs clearly state something should work (but it doesn't)

thank you.

[janiceilene]

Thanks for opening a new issue and giving so much additional context @ahmadnassri! I'll triage this for the team to take another look 👀

[skedwards88]

@ahmadnassri Thanks for bringing this to our attention--and thanks especially for the detailed issue body! I have verified what you reported. I am confirming internally that this is the expected behavior and will let you know what I learn.

[ahmadnassri]

thank you both @janiceilene @skedwards88

[skedwards88]

@ahmadnassri I checked in with our engineering team, and the docs are incorrect. Only GET /repos/{owner}/{repo} returns template_repository. (The other examples that include template_repository are incorrect.) Additionally, all endpoints that include is_template in their example response require the baptiste preview. This needs to be fixed internally, so I will close this issue and open an internal issue transfer this issue to the appropriate repo. Thank you for catching this error! ✨

[ahmadnassri]

would you post here when the corrections have been made public?

[docubot]

Thank you for opening this issue! Changes to the REST API schema can be requested in github/rest-api-description. I will transfer your issue over to that open source repo.

[becco]

Hi @ahmadnassri! Thank you for the detailed description, and sorry for the delay. We just fixed this issue so I'm closing it now, but kindly let us know if you run into anything else. ✨