jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Update "Getting started with the REST API" (#45525)

Browse Source 
Co-authored-by: Sarah Edwards <skedwards88@github.com>
This commit is contained in:
Jess Hosman
2023-12-05 14:57:27 -07:00
committed by GitHub
parent 38a4a081dd
commit 3d44ee5f94
8 changed files with 562 additions and 835 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
content/github-cli/github-cli/quickstart.md
View File

@@ -19,26 +19,7 @@ shortTitle: Quickstart
## Prerequisites
1. Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository.
1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %}
{%- ifversion fpt or ghec %}
```shell
gh auth login
```
{%- else %}
```shell
gh auth login --hostname HOSTNAME
```
{%- endif %}
1. Follow the on-screen prompts.
{% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use `git push`, `git pull`, and so on, without needing to set up a separate credential manager or use SSH.
{% data reusables.rest-api.github-cli-install-and-auth %}
## Some useful commands
@@ -101,7 +82,7 @@ You can change configuration settings and add aliases or extensions, to make {%
- Enter `gh config set SUBCOMMANDS` to configure {% data variables.product.prodname_cli %}'s settings, replacing `SUBCOMMANDS` with the setting you want to adjust.
For example, you can specify the text editor that's used when a {% data variables.product.prodname_cli %} command requires you to edit text - such as when you add the body text for a new issue you're creating. To set your preferred text editor to {% data variables.product.prodname_vscode %} enter `gh config set editor "code -w"`. The `-w` (or `--wait`) flag in this example causes the command to wait for the file to be closed in {% data variables.product.prodname_vscode %} before proceeding with the next step in your terminal.
For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set).
- Define aliases for commands that you commonly run. For example, if you run `gh alias set prd "pr create --draft"`, you will then be able to run `gh prd` to quickly open a draft pull request. For more information, see [`gh alias`](https://cli.github.com/manual/gh_alias).

929
content/rest/guides/getting-started-with-the-rest-api.md
View File

File diff suppressed because it is too large Load Diff

57
content/rest/overview/authenticating-to-the-rest-api.md
View File

@@ -18,7 +18,9 @@ shortTitle: Authenticating
Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
You can authenticate your request by sending a token in the `Authorization` header of your request. In the following example, replace `YOUR-TOKEN` with a reference to your token:
To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow.
After creating a token, you can authenticate your request by sending the token in the `Authorization` header of your request. For example, in the folllowing request, replace `YOUR-TOKEN` with a reference to your token:
```shell
curl --request GET \
@@ -33,7 +35,11 @@ curl --request GET \
{% endnote %}
If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response.
### Failed login limit
If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response. Authenticating with invalid credentials will initially return a `401 Unauthorized` response.
After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with a `403 Forbidden` response. For more information, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)."
## Authenticating with a {% data variables.product.pat_generic %}
@@ -93,6 +99,50 @@ If you are the owner of a {% data variables.product.prodname_github_app %} or {%
If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
If this is not possible, you can store your token as a secret and use the name of your secret in your {% data variables.product.prodname_actions %} workflow. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
### Authenticating in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %}
To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %}, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute the {% data variables.product.prodname_cli %} `api` subcommand. For more information about the `run` keyword, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path)."{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
```yaml
jobs:
use_api:
runs-on: ubuntu-latest
permissions: {}
steps:
- env:
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
run: |
gh api /PATH
```
### Authenticating in a {% data variables.product.prodname_actions %} workflow using `curl`
To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using `curl`, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute a `curl` request to the API. For more information about the `run` keyword, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path)."{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
```yaml copy
jobs:
use_api:
runs-on: ubuntu-latest
permissions: {}
steps:
- env:
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
run: |
curl --request GET \
--url "{% data variables.product.api_url_code %}/PATH" \
--header "Authorization: Bearer $GH_TOKEN"
```
### Authenticating in a {% data variables.product.prodname_actions %} workflow using JavaScript
For an example of how to authenticate in a {% data variables.product.prodname_actions %} workflow using JavaScript, see "[AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-in-github-actions)."
## Authenticating with username and password
{% ifversion ghes %}
@@ -114,4 +164,5 @@ Authentication with username and password is not supported. If you try to authen
## Further reading
- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)"
- "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#authenticating)"

204
content/rest/overview/resources-in-the-rest-api.md
View File

@@ -12,167 +12,6 @@ topics:
- API
---
{% ifversion api-date-versioning %}
## API version
Available resources may vary between REST API versions. You should use the `X-GitHub-Api-Version` header to specify an API version. For more information, see "[AUTOTITLE](/rest/overview/api-versions)."
{% endif %}
## Schema
{% ifversion fpt or ghec %}All API access is over HTTPS, and{% else %}The API is{% endif %} accessed from `{% data variables.product.api_url_code %}`. All data is
sent and received as JSON.
```shell
$ curl -I {% data variables.product.api_url_pre %}/users/octocat/orgs
> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394{% ifversion ghes %}
> X-GitHub-Enterprise-Version: {{ currentVersion | remove: "enterprise-server@" }}.0{% elsif ghae %}
> X-GitHub-Enterprise-Version: GitHub AE{% endif %}
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff
```
Blank fields are included as `null` instead of being omitted.
All timestamps return in UTC time, ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
For more information about timezones in timestamps, see [this section](#timezones).
### Summary representations
When you fetch a list of resources, the response includes a _subset_ of the
attributes for that resource. This is the "summary" representation of the
resource. (Some attributes are computationally expensive for the API to provide.
For performance reasons, the summary representation excludes those attributes.
To obtain those attributes, fetch the "detailed" representation.)
**Example**: When you get a list of repositories, you get the summary
representation of each repository. Here, we fetch the list of repositories owned
by the [octokit](https://github.com/octokit) organization:
GET /orgs/octokit/repos
### Detailed representations
When you fetch an individual resource, the response typically includes _all_
attributes for that resource. This is the "detailed" representation of the
resource. (Note that authorization sometimes influences the amount of detail
included in the representation.)
**Example**: When you get an individual repository, you get the detailed
representation of the repository. Here, we fetch the
[octokit/octokit.rb](https://github.com/octokit/octokit.rb) repository:
GET /repos/octokit/octokit.rb
The documentation provides an example response for each API method. The example
response illustrates all attributes that are returned by that method.
## Authentication
{% data variables.product.company_short %} recommends that you create a token to authenticate to the REST API. For more information about which type of token to create, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)."
You can authenticate your request by sending a token in the `Authorization` header of your request:
```shell
curl --request GET \
--url "{% data variables.product.api_url_code %}/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"{% ifversion api-date-versioning %} \
--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
```
{% note %}
**Note:** {% data reusables.getting-started.bearer-vs-token %}
{% endnote %}
If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response.
{% ifversion fpt or ghes or ghec %}
### OAuth2 key/secret
{% data reusables.apps.deprecating_auth_with_query_parameters %}
```shell
curl -u my_client_id:my_client_secret '{% data variables.product.api_url_pre %}/user/repos'
```
Using your `client_id` and `client_secret` does _not_ authenticate as a user, it will only identify your {% data variables.product.prodname_oauth_app %} to increase your rate limit. Permissions are only granted to users, not applications, and you will only get back data that an unauthenticated user would see. Don't leak your {% data variables.product.prodname_oauth_app %}'s client secret to your users.
{% ifversion ghes %}
You will be unable to authenticate using your OAuth2 key and secret while in private mode, and trying to authenticate will return `401 Unauthorized`. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-private-mode)".
{% endif %}
{% endif %}
{% ifversion fpt or ghec %}
For more information about rate limits for {% data variables.product.prodname_oauth_apps %}, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)."
{% endif %}
### Failed login limit
Authenticating with invalid credentials will return `401 Unauthorized`:
```shell
$ curl -I {% data variables.product.api_url_pre %} --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401
> {
> "message": "Bad credentials",
> "documentation_url": "{% data variables.product.doc_url_pre %}"
> }
```
After detecting several requests with invalid credentials within a short period,
the API will temporarily reject all authentication attempts for that user
(including ones with valid credentials) with `403 Forbidden`:
```shell
> HTTP/2 403
> {
> "message": "Maximum number of login attempts exceeded. Please try again later.",
> "documentation_url": "{% data variables.product.doc_url_pre %}"
> }
```
## Parameters
Many API methods take optional parameters. For `GET` requests, any parameters not
specified as a segment in the path can be passed as an HTTP query string
parameter:
```shell
curl -i "{% data variables.product.api_url_pre %}/repos/vmg/redcarpet/issues?state=closed"
```
In this example, the 'vmg' and 'redcarpet' values are provided for the `:owner`
and `:repo` parameters in the path while `:state` is passed in the query
string.
For `POST`, `PATCH`, `PUT`, and `DELETE` requests, parameters not included in the URL should be encoded as JSON
with a Content-Type of 'application/json':
```shell
curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' {% data variables.product.api_url_pre %}/authorizations
```
## Root endpoint
You can issue a `GET` request to the root endpoint to get all the endpoint categories that the REST API supports:
@@ -186,20 +25,6 @@ $ curl {% ifversion fpt or ghae or ghec %}
See the guide on "[AUTOTITLE](/graphql/guides/using-global-node-ids)" for detailed information about how to find `node_id`s via the REST API and use them in GraphQL operations.
## HTTP verbs
Where possible, the {% data variables.product.product_name %} REST API strives to use appropriate HTTP verbs for each
action. Note that HTTP verbs are case-sensitive.
Verb | Description
-----|-----------
`HEAD` | Can be issued against any resource to get just the HTTP header info.
`GET` | Used for retrieving resources.
`POST` | Used for creating resources.
`PATCH` | Used for updating resources with partial JSON data. For instance, an Issue resource has `title` and `body` attributes. A `PATCH` request may accept one or more of the attributes to update the resource.
`PUT` | Used for replacing resources or collections. For `PUT` requests with no `body` attribute, be sure to set the `Content-Length` header to zero.
`DELETE` |Used for deleting resources.
## Hypermedia
All resources may have one or more `*_url` properties linking to other
@@ -221,35 +46,6 @@ gem:
>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"
{% ifversion fpt or ghec %}
## User agent required
All API requests MUST include a valid `User-Agent` header. Requests with no `User-Agent`
header will be rejected. We request that you use your {% data variables.product.product_name %} username, or the name of your
application, for the `User-Agent` header value. This allows us to contact you if there are problems.
Here's an example:
```shell
User-Agent: Awesome-Octocat-App
```
curl sends a valid `User-Agent` header by default. If you provide an invalid `User-Agent` header via curl (or via an alternative client), you will receive a `403 Forbidden` response:
```shell
$ curl -IH 'User-Agent: ' {% data variables.product.api_url_pre %}/meta
> HTTP/1.0 403 Forbidden
> Connection: close
> Content-Type: text/html
> Request forbidden by administrative rules.
> Please make sure your request has a User-Agent header.
> Check for other possible causes.
```
{% endif %}
## Cross origin resource sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from

156
content/rest/quickstart.md
View File

@@ -15,52 +15,37 @@ redirect_from:
- /v3/guides/getting-started
---
This article describes how to quickly get started with the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, JavaScript, or `curl`. For a more detailed guide, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api)."
## Introduction
This article describes how to quickly get started with the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, `curl`, or JavaScript. For a more detailed guide, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api)."
{% cli %}
## Getting started using {% data variables.product.prodname_cli %}
### Using {% data variables.product.prodname_cli %} in the command line
## Using {% data variables.product.prodname_cli %} in the command line
{% data variables.product.prodname_cli %} is the easiest way to use the {% data variables.product.prodname_dotcom %} REST API from the command line.
{% ifversion ghes or ghae %}
{% note %}
{% data reusables.rest-api.github-cli-install-and-auth %}
**Note:** The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. Alternatively, rerun the `gh auth login` command to authenticate to {% data variables.product.prodname_dotcom_the_website %} instead of {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}.
1. Make a request using the {% data variables.product.prodname_cli %} `api` subcommand, followed by the path. Use the `--method` or `-X` flag to specify the method. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api).
{% endnote %}
{% endif %}
This example makes a request to the "Get Octocat" endpoint, which uses the method `GET` and the path `/octocat`. For the full reference documentation for this endpoint, see "[AUTOTITLE](/rest/meta/meta#get-octocat)."
1. Install {% data variables.product.prodname_cli %} if you haven't installed it yet. For installation instructions, see the [{% data variables.product.prodname_cli %} repository](https://github.com/cli/cli#installation).
1. Use the `auth login` subcommand to authenticate to {% data variables.product.prodname_cli %}. For more information, see the [{% data variables.product.prodname_cli %} `auth login` documentation](https://cli.github.com/manual/gh_auth_login).
```shell
gh auth login
```shell copy
gh api /octocat --method GET
```
1. Use the `api` subcommand to make your API request. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api).
```shell
gh api repos/octocat/Spoon-Knife/issues
```
### Using {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %}
## Using {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %}
You can also use {% data variables.product.prodname_cli %} in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/using-github-cli-in-workflows)."
### Authenticating with an access token
Instead of using the `gh auth login` command, pass an access token as an environment variable called `GH_TOKEN`. {% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
{% ifversion ghes or ghae %}
{% note %}
The following example workflow uses the "[List repository issues](/rest/issues/issues#list-repository-issues)" endpoint, and requests a list of issues in {% ifversion ghes or ghae %}a repository you specify{% else %}the `octocat/Spoon-Knife` repository{% endif %}.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
**Note:** The following example workflows are intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the examples using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}.
{% endnote %}
{% endif %}
```yaml
```yaml copy
on:
workflow_dispatch:
jobs:
@@ -72,19 +57,21 @@ jobs:
- env:
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
run: |
gh api repos/octocat/Spoon-Knife/issues
gh api {% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}
```
### Authenticating with a {% data variables.product.prodname_github_app %}
If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow:
1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)" in the REST API documentation. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)."
1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example:
1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
```yaml
```yaml copy
{% ifversion ghes < 3.12 %}
{% data reusables.actions.actions-not-certified-by-github-comment %}
{% data reusables.actions.actions-use-sha-pinning-comment %}
{% endif %}
on:
@@ -103,22 +90,18 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
env:
GH_TOKEN: {% raw %}${{ steps.generate_token.outputs.token }}{% endraw %}
run: |
gh api repos/octocat/Spoon-Knife/issues
gh api {% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}
```
{% endcli %}
{% javascript %}
## Getting started using JavaScript
## Using Octokit.js
You can use Octokit.js to interact with the {% data variables.product.prodname_dotcom %} REST API in your JavaScript scripts. For more information, see "[Scripting with the REST API and JavaScript](/rest/guides/scripting-with-the-rest-api-and-javascript)."
### Using Octokit.js
{% data reusables.rest-api.quickstart-location-javascript-admonition %}
1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. For more information, see "[Creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)."
1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access that endpoint. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)."
{% warning %}
@@ -136,30 +119,33 @@ You can use Octokit.js to interact with the {% data variables.product.prodname_d
1. Install `octokit`. For example, `npm install octokit`. For other ways to install or load `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme).
1. Import `octokit` in your script. For example, `import { Octokit } from "octokit";`. For other ways to import `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme).
1. Create an instance of `Octokit` with your token. Replace `YOUR-TOKEN` with your token.
1. Create an instance of `Octokit` with your token.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `YOUR-TOKEN` with your token.
```javascript
const octokit = new Octokit({
```javascript copy
const octokit = new Octokit({ {% ifversion ghes or ghae %}
baseUrl: "{% data variables.product.api_url_code %}",{% endif %}
auth: 'YOUR-TOKEN'
});
```
1. Use `octokit.request` to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For example, in the following request the HTTP method is `GET`, the path is `/repos/{owner}/{repo}/issues`, and the parameters are `owner: "octocat"` and `repo: "Spoon-Knife"`.
1. Use `octokit.request` to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For more information about parameters, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#using-parameters)."
```javascript
For example, in the following request the HTTP method is `GET`, the path is `/repos/{owner}/{repo}/issues`, and the parameters are {% ifversion ghes or ghae %}`owner: "REPO-OWNER"` and `repo: "REPO-NAME"`{% else %}`owner: "octocat"` and `repo: "Spoon-Knife"`{% endif %}.{% ifversion ghes or ghae %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %}
```javascript copy
await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "Spoon-Knife",
owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}",
repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}",
});
```
### Using Octokit.js in {% data variables.product.prodname_actions %}
## Using Octokit.js in {% data variables.product.prodname_actions %}
You can also execute your JavaScript scripts in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
### Authenticating with an access token
{% data reusables.rest-api.quickstart-location-javascript-admonition %}
{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
The following example workflow:
@@ -168,8 +154,6 @@ The following example workflow:
1. Installs `octokit`
1. Stores the value of `GITHUB_TOKEN` as an environment variable called `TOKEN` and runs `.github/actions-scripts/use-the-api.mjs`, which can access that environment variable as `process.env.TOKEN`
Example workflow:
```yaml
on:
workflow_dispatch:
@@ -198,19 +182,20 @@ jobs:
TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
```
Example JavaScript script, with the file path `.github/actions-scripts/use-the-api.mjs`:
The following is an example Javascript script with the file path `.github/actions-scripts/use-the-api.mjs`.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
```javascript
import { Octokit } from "octokit"
const octokit = new Octokit({
const octokit = new Octokit({ {% ifversion ghes or ghae %}
baseUrl: "{% data variables.product.api_url_code %}",{% endif %}
auth: process.env.TOKEN
});
try {
const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "Spoon-Knife",
owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}",
repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}",
});
const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})
@@ -222,6 +207,8 @@ try {
}
```
### Authenticating with a {% data variables.product.prodname_github_app %}
If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow:
1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
@@ -231,7 +218,7 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
```yaml
{% ifversion ghes < 3.12 %}
{% data reusables.actions.actions-not-certified-by-github-comment %}
{% data reusables.actions.actions-use-sha-pinning-comment %}
{% endif %}
on:
@@ -248,17 +235,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
with:
node-version: '16.17.0'
cache: npm
- name: Install dependencies
run: npm install octokit
- name: Generate token
id: generate_token
uses: {% ifversion ghes < 3.12 %}tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92{% else %}actions/create-github-app-token@v1{% endif %}
with:
app_id: {% raw %}${{ secrets.APP_ID }}{% endraw %}
private_key: {% raw %}${{ secrets.APP_PEM }}{% endraw %}
- name: Run script
run: |
node .github/actions-scripts/use-the-api.mjs
@@ -271,23 +258,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
{% curl %}
## Getting started using `curl`
## Using `curl` in the command line
### Using `curl` in the command line
{% ifversion ghes or ghae %}
{% note %}
**Notes:**
- The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `https://api.github.com` with `{% data variables.product.api_url_code %}`, and replace `HOSTNAME` with the hostname for {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. You must also replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}.
- If you want to make API requests from the command line, {% data variables.product.prodname_dotcom %} recommends that you use {% data variables.product.prodname_cli %}, which simplifies authentication and requests. For more information about getting started with the REST API using {% data variables.product.prodname_cli %}, see the {% data variables.product.prodname_cli %} version of this article.
**Note:** If you want to make API requests from the command line, {% data variables.product.prodname_dotcom %} recommends that you use {% data variables.product.prodname_cli %}, which simplifies authentication and requests. For more information about getting started with the REST API using {% data variables.product.prodname_cli %}, see the {% data variables.product.prodname_cli %} version of this article.
{% endnote %}
{% endif %}
1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` in the command line. If the output is information about the version of `curl`, it is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html).
1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. For more information, see "[Creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)."
1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` in the command line. If the output provides information about the version of `curl`, that means `curl` is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html).
1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access the endpoint. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)."
{% warning %}
@@ -303,11 +284,11 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
{% endwarning %}
1. Use the `curl` command to make your request. Pass your token in an `Authorization` header. Replace `YOUR-TOKEN` with your token.
1. Use the `curl` command to make your request. Pass your token in an `Authorization` header.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} Replace `YOUR-TOKEN` with your token.
```shell
```shell copy
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
@@ -318,24 +299,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
{% endnote %}
### Using `curl` commands in {% data variables.product.prodname_actions %}
## Using `curl` commands in {% data variables.product.prodname_actions %}
You can also use `curl` commands in your {% data variables.product.prodname_actions %} workflows.
### Authenticating with an access token
{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
{% ifversion ghes or ghae %}
{% note %}
{% ifversion ghes or ghae %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
**Note:** The following example workflows are intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the examples using {% data variables.product.product_name %}, note the following differences.
- You must replace `https://api.github.com` with `{% data variables.product.api_url_code %}`, and replace `HOSTNAME` with the hostname for {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghae %}{% data variables.product.product_name %}{% endif %}.
- You must replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}.
{% endnote %}
{% endif %}
```yaml
```yaml copy
on:
workflow_dispatch:
jobs:
@@ -348,18 +322,20 @@ jobs:
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
run: |
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $GH_TOKEN"
```
### Authenticating with a {% data variables.product.prodname_github_app %}
If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow:
1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)."
1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example:
1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
```yaml
```yaml copy
{% ifversion ghes < 3.12 %}
{% data reusables.actions.actions-not-certified-by-github-comment %}
@@ -383,7 +359,7 @@ If you are authenticating with a {% data variables.product.prodname_github_app %
GH_TOKEN: {% raw %}${{ steps.generate_token.outputs.token }}{% endraw %}
run: |
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $GH_TOKEN"

20
data/reusables/rest-api/github-cli-install-and-auth.md Normal file
View File

@@ -0,0 +1,20 @@
1. Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository.
1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %}
{%- ifversion fpt or ghec %}
```shell
gh auth login
```
{%- else %}
```shell
gh auth login --hostname HOSTNAME
```
{%- endif %}
1. Follow the on-screen prompts.
{% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use Git commands like `git push` and `git pull` without needing to set up a separate credential manager or use SSH.

7
data/reusables/rest-api/quickstart-location-javascript-admonition.md
View File

@@ -1,7 +0,0 @@
{% ifversion ghes or ghae %}
{% note %}
**Note:** The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. Alternatively, you can create a new `Octokit` instance without specifying `baseURL`.
{% endnote %}
{% endif %}

1
data/variables/rest.yml Normal file
View File

@@ -0,0 +1 @@
example_request_url: '/repos{% ifversion ghes or ghae %}/REPO-OWNER/REPO-NAME{% else %}/octocat/Spoon-Knife{% endif %}/issues'