Skip to content

Link to upstream JSON API from our docs #740

Description

@stephenplusplus

Introduced in #721 (comment)

Our APIs will generally try to make the upstream API a little more user-friendly by using more logical names or trimming some of the verbosity. And then we document the things we handle (things like maxResults, pageSize, pageToken, etc). But, most of our APIs are also a pass-through to the upstream API, which will have many more options that we don't document.

I don't think we should document everything, as there's already a place for that. And I don't think we have to limit the user's input to include only the things "we approve". We should just link to the upstream API's docs to show the full list of options and their official descriptions.

Example:

Link https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.16.0/bigquery/dataset?method=createTable to https://cloud.google.com/bigquery/docs/reference/v2/tables/insert

Activity

  1. self-assigned this
    on Aug 7, 2015
  2. callmehiphop commented on Aug 7, 2015

    @callmehiphop
    Contributor

    Is this something you only want to do where we don't provide a complete list of the available options or should we just link every method to it's upstream counterpart?

  3. stephenplusplus commented on Aug 7, 2015

    @stephenplusplus
    ContributorAuthor

    Always link. I don't know if any of our method docs are actually 1:1 with the upstream. But yeah, either way, it will still be helpful for the user to see exactly what's going on from the official docs. It also will help them see exactly what our apiResponse argument will hold.

  4. callmehiphop commented on Aug 7, 2015

    @callmehiphop
    Contributor

    Is search documented anywhere? I saw a few links scattered throughout the JSDoc but they're all dead now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions