Repository navigation
api --preview docs are still very unhelpful #11239
Description
Activity
Thanks for opening this issue, @jsoref! 🙏
I think I agree with you that the docs is not clear about the function of the
--previewoption. Seems like what it was before #3433 was kind of clearer.I can suggest an improvement like this:
-p, --preview names Opt into GitHub API previews (names are comma separated and should omit the `-preview` suffix)What do you think, @jsoref? Do you that's clear enough for users who are seeing it for the first time?
That prose is definitely better.
I'm not a fan of the
omitI think "without" is easier to understand. Omit as a verb requires an actor and this is passive prose.That still only addresses half the problem. What is a preview? Is it really only a content type response?
I think defining a preview option as something related to a request's
Content-Typeheader field, is both confusing and too much detail. I imagine, as a user, I'd want to see there's a way to opt into upcoming API features that are not yet part of the stable release. Perhaps, this can be explained like this in the--helpdocs of the command:$ gh api --help Makes an authenticated HTTP request to the GitHub API and prints the response. ... The command supports invoking preview-stage API endpoints/features, by providing the `--preview` option followed by the name of the preview features to enable. ...What do you think, @jsoref?
Maybe.
Let's start with the easier part:
-p, --preview names Opt into GitHub API previews (names should exclude `-preview` and be comma separated)$ gh api --help Makes an authenticated HTTP request to the GitHub API and prints the response. ... This command supports invoking preview-stage API endpoints/features, when using the `--preview` option with names of preview features to enable. ...That still leaves users the problem of discovering what previews are. Which seems incredibly challenging.
I found:
- https://github.blog/changelog/2021-10-14-rest-api-preview-promotions/ which talks about Previews
- https://github.blog/changelog/2024-10-18-new-terminology-for-github-previews/ which talks about Previews as replacing Alpha and Beta (but it's after the 2021 thing that clearly was using Preview 😕)
But I haven't been able to construct any query to actually find recent previews...
Regarding the discovery of preview features, I think you should consult with API schemas:
- For the REST API, OpenAPI specs are available as explained in this doc. You can download the OpenAPI spec (based on the API/product version you're interested) and look for
previewskeys. As I checked forapi.github.com, there's no ongoing preview at the moment (i.e.previews: []). - For the GraphQL API, you can find the link to download the schema in this doc. At the top of the schema, you can see the definition of a
@previewdirective like this:Like REST APIs, I couldn't find anything decorated with thisdirective @preview( """ The identifier of the API preview that toggles this field. """ toggledBy: String! ) on ARGUMENT_DEFINITION | ENUM | ENUM_VALUE | FIELD_DEFINITION | INPUT_FIELD_DEFINITION | INPUT_OBJECT | INTERFACE | OBJECT | SCALAR | UNION
@previewdirective. So, I guess there's no preview here either.
As a disclaimer, I haven't tried discovering previews so far, so I maybe wrong.
Reacted by Josh Soref- For the REST API, OpenAPI specs are available as explained in this doc. You can download the OpenAPI spec (based on the API/product version you're interested) and look for
I think we're ready to put down the A/C for this issue at this stage.
Acceptance Criteria
When I run
gh api --help
Then I see the--previewoption is clearly documented like this:$ gh api --help Makes an authenticated HTTP request to the GitHub API and prints the response. ... This command supports invoking preview-stage API endpoints/features, when using the `--preview` option with names of preview features to enable. ... -p, --preview names Opt into GitHub API previews (names should exclude '-preview' and be comma separated) ...Reacted by Josh Soref
Describe the bug
Means nothing to me.
I can't tell if this means that requests for certain apis will be sent without
-preview. If that's the goal, then, the text should say "Send requests without-preview", but I don't think that's what's going on.If it means "Include specific preview mime types in accepts request", then it should say something like that. My guess is that the goal is more like "GitHUB API preview
namesto include in request accept headers (namesshould omit-preview, but requests will include the suffix)."Affected version
Steps to reproduce the behavior
gh api --help|grep -A1 previewExpected vs actual behavior
A clear and concise explanation of what
previewdoesapi --previewoption #3433 asked for an improvement here`names`is present in the code, the`s are lost in the help output:cli/pkg/cmd/api/api.go
Line 279 in df5e6d9