Skip to content

Commit 3d44ee5

Browse files
jhosmanskedwards88
jhosman
and
skedwards88
authored
Update "Getting started with the REST API" (#45525)
Co-authored-by: Sarah Edwards <[email protected]>
1 parent 38a4a08 commit 3d44ee5

8 files changed

+449
-722
lines changed

‎content/github-cli/github-cli/quickstart.md

+2-21
Original file line numberDiff line numberDiff line change
@@ -19,26 +19,7 @@ shortTitle: Quickstart
1919

2020
## Prerequisites
2121

22-
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.
23-
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 %}
24-
25-
{%- ifversion fpt or ghec %}
26-
27-
```shell
28-
gh auth login
29-
```
30-
31-
{%- else %}
32-
33-
```shell
34-
gh auth login --hostname HOSTNAME
35-
```
36-
37-
{%- endif %}
38-
39-
1. Follow the on-screen prompts.
40-
41-
{% 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.
22+
{% data reusables.rest-api.github-cli-install-and-auth %}
4223

4324
## Some useful commands
4425

@@ -101,7 +82,7 @@ You can change configuration settings and add aliases or extensions, to make {%
10182
- Enter `gh config set SUBCOMMANDS` to configure {% data variables.product.prodname_cli %}'s settings, replacing `SUBCOMMANDS` with the setting you want to adjust.
10283

10384
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.
104-
85+
10586
For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set).
10687

10788
- 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).

‎content/rest/guides/getting-started-with-the-rest-api.md

+306-397
Large diffs are not rendered by default.

‎content/rest/overview/authenticating-to-the-rest-api.md

+54-3
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,9 @@ shortTitle: Authenticating
1818

1919
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.
2020

21-
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:
21+
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.
22+
23+
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:
2224

2325
```shell
2426
curl --request GET \
@@ -33,7 +35,11 @@ curl --request GET \
3335

3436
{% endnote %}
3537

36-
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.
38+
### Failed login limit
39+
40+
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.
41+
42+
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)."
3743

3844
## Authenticating with a {% data variables.product.pat_generic %}
3945

@@ -93,6 +99,50 @@ If you are the owner of a {% data variables.product.prodname_github_app %} or {%
9399

94100
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)."
95101

102+
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)."
103+
104+
### Authenticating in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %}
105+
106+
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)."
107+
108+
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 %}
109+
110+
```yaml
111+
jobs:
112+
use_api:
113+
runs-on: ubuntu-latest
114+
permissions: {}
115+
steps:
116+
- env:
117+
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
118+
run: |
119+
gh api /PATH
120+
```
121+
122+
### Authenticating in a {% data variables.product.prodname_actions %} workflow using `curl`
123+
124+
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)."
125+
126+
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 %}
127+
128+
```yaml copy
129+
jobs:
130+
use_api:
131+
runs-on: ubuntu-latest
132+
permissions: {}
133+
steps:
134+
- env:
135+
GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
136+
run: |
137+
curl --request GET \
138+
--url "{% data variables.product.api_url_code %}/PATH" \
139+
--header "Authorization: Bearer $GH_TOKEN"
140+
```
141+
142+
### Authenticating in a {% data variables.product.prodname_actions %} workflow using JavaScript
143+
144+
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)."
145+
96146
## Authenticating with username and password
97147

98148
{% ifversion ghes %}
@@ -114,4 +164,5 @@ Authentication with username and password is not supported. If you try to authen
114164

115165
## Further reading
116166

117-
- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
167+
- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)"
168+
- "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#authenticating)"

‎content/rest/overview/resources-in-the-rest-api.md

-204
Original file line numberDiff line numberDiff line change
@@ -12,167 +12,6 @@ topics:
1212
- API
1313
---
1414

15-
{% ifversion api-date-versioning %}
16-
17-
## API version
18-
19-
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)."
20-
21-
{% endif %}
22-
23-
## Schema
24-
25-
{% 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
26-
sent and received as JSON.
27-
28-
```shell
29-
$ curl -I {% data variables.product.api_url_pre %}/users/octocat/orgs
30-
31-
> HTTP/2 200
32-
> Server: nginx
33-
> Date: Fri, 12 Oct 2012 23:33:14 GMT
34-
> Content-Type: application/json; charset=utf-8
35-
> ETag: "a00049ba79152d03380c34652f2cb612"
36-
> X-GitHub-Media-Type: github.v3
37-
> x-ratelimit-limit: 5000
38-
> x-ratelimit-remaining: 4987
39-
> x-ratelimit-reset: 1350085394{% ifversion ghes %}
40-
> X-GitHub-Enterprise-Version: {{ currentVersion | remove: "enterprise-server@" }}.0{% elsif ghae %}
41-
> X-GitHub-Enterprise-Version: GitHub AE{% endif %}
42-
> Content-Length: 5
43-
> Cache-Control: max-age=0, private, must-revalidate
44-
> X-Content-Type-Options: nosniff
45-
```
46-
47-
Blank fields are included as `null` instead of being omitted.
48-
49-
All timestamps return in UTC time, ISO 8601 format:
50-
51-
YYYY-MM-DDTHH:MM:SSZ
52-
53-
For more information about timezones in timestamps, see [this section](#timezones).
54-
55-
### Summary representations
56-
57-
When you fetch a list of resources, the response includes a _subset_ of the
58-
attributes for that resource. This is the "summary" representation of the
59-
resource. (Some attributes are computationally expensive for the API to provide.
60-
For performance reasons, the summary representation excludes those attributes.
61-
To obtain those attributes, fetch the "detailed" representation.)
62-
63-
**Example**: When you get a list of repositories, you get the summary
64-
representation of each repository. Here, we fetch the list of repositories owned
65-
by the [octokit](https://github.com/octokit) organization:
66-
67-
GET /orgs/octokit/repos
68-
69-
### Detailed representations
70-
71-
When you fetch an individual resource, the response typically includes _all_
72-
attributes for that resource. This is the "detailed" representation of the
73-
resource. (Note that authorization sometimes influences the amount of detail
74-
included in the representation.)
75-
76-
**Example**: When you get an individual repository, you get the detailed
77-
representation of the repository. Here, we fetch the
78-
[octokit/octokit.rb](https://github.com/octokit/octokit.rb) repository:
79-
80-
GET /repos/octokit/octokit.rb
81-
82-
The documentation provides an example response for each API method. The example
83-
response illustrates all attributes that are returned by that method.
84-
85-
## Authentication
86-
87-
{% 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)."
88-
89-
You can authenticate your request by sending a token in the `Authorization` header of your request:
90-
91-
```shell
92-
curl --request GET \
93-
--url "{% data variables.product.api_url_code %}/octocat" \
94-
--header "Authorization: Bearer YOUR-TOKEN"{% ifversion api-date-versioning %} \
95-
--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
96-
```
97-
98-
{% note %}
99-
100-
**Note:** {% data reusables.getting-started.bearer-vs-token %}
101-
102-
{% endnote %}
103-
104-
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.
105-
106-
{% ifversion fpt or ghes or ghec %}
107-
108-
### OAuth2 key/secret
109-
110-
{% data reusables.apps.deprecating_auth_with_query_parameters %}
111-
112-
```shell
113-
curl -u my_client_id:my_client_secret '{% data variables.product.api_url_pre %}/user/repos'
114-
```
115-
116-
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.
117-
118-
{% ifversion ghes %}
119-
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)".
120-
{% endif %}
121-
{% endif %}
122-
123-
{% ifversion fpt or ghec %}
124-
125-
For more information about rate limits for {% data variables.product.prodname_oauth_apps %}, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)."
126-
127-
{% endif %}
128-
129-
### Failed login limit
130-
131-
Authenticating with invalid credentials will return `401 Unauthorized`:
132-
133-
```shell
134-
$ curl -I {% data variables.product.api_url_pre %} --header "Authorization: Bearer INVALID-TOKEN"
135-
> HTTP/2 401
136-
137-
> {
138-
> "message": "Bad credentials",
139-
> "documentation_url": "{% data variables.product.doc_url_pre %}"
140-
> }
141-
```
142-
143-
After detecting several requests with invalid credentials within a short period,
144-
the API will temporarily reject all authentication attempts for that user
145-
(including ones with valid credentials) with `403 Forbidden`:
146-
147-
```shell
148-
> HTTP/2 403
149-
> {
150-
> "message": "Maximum number of login attempts exceeded. Please try again later.",
151-
> "documentation_url": "{% data variables.product.doc_url_pre %}"
152-
> }
153-
```
154-
155-
## Parameters
156-
157-
Many API methods take optional parameters. For `GET` requests, any parameters not
158-
specified as a segment in the path can be passed as an HTTP query string
159-
parameter:
160-
161-
```shell
162-
curl -i "{% data variables.product.api_url_pre %}/repos/vmg/redcarpet/issues?state=closed"
163-
```
164-
165-
In this example, the 'vmg' and 'redcarpet' values are provided for the `:owner`
166-
and `:repo` parameters in the path while `:state` is passed in the query
167-
string.
168-
169-
For `POST`, `PATCH`, `PUT`, and `DELETE` requests, parameters not included in the URL should be encoded as JSON
170-
with a Content-Type of 'application/json':
171-
172-
```shell
173-
curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' {% data variables.product.api_url_pre %}/authorizations
174-
```
175-
17615
## Root endpoint
17716

17817
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 %}
18625

18726
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.
18827

189-
## HTTP verbs
190-
191-
Where possible, the {% data variables.product.product_name %} REST API strives to use appropriate HTTP verbs for each
192-
action. Note that HTTP verbs are case-sensitive.
193-
194-
Verb | Description
195-
-----|-----------
196-
`HEAD` | Can be issued against any resource to get just the HTTP header info.
197-
`GET` | Used for retrieving resources.
198-
`POST` | Used for creating resources.
199-
`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.
200-
`PUT` | Used for replacing resources or collections. For `PUT` requests with no `body` attribute, be sure to set the `Content-Length` header to zero.
201-
`DELETE` |Used for deleting resources.
202-
20328
## Hypermedia
20429

20530
All resources may have one or more `*_url` properties linking to other
@@ -221,35 +46,6 @@ gem:
22146
>> tmpl.expand all: 1, participating: 1
22247
=> "/notifications?all=1&participating=1"
22348

224-
{% ifversion fpt or ghec %}
225-
226-
## User agent required
227-
228-
All API requests MUST include a valid `User-Agent` header. Requests with no `User-Agent`
229-
header will be rejected. We request that you use your {% data variables.product.product_name %} username, or the name of your
230-
application, for the `User-Agent` header value. This allows us to contact you if there are problems.
231-
232-
Here's an example:
233-
234-
```shell
235-
User-Agent: Awesome-Octocat-App
236-
```
237-
238-
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:
239-
240-
```shell
241-
$ curl -IH 'User-Agent: ' {% data variables.product.api_url_pre %}/meta
242-
> HTTP/1.0 403 Forbidden
243-
> Connection: close
244-
> Content-Type: text/html
245-
246-
> Request forbidden by administrative rules.
247-
> Please make sure your request has a User-Agent header.
248-
> Check for other possible causes.
249-
```
250-
251-
{% endif %}
252-
25349
## Cross origin resource sharing
25450

25551
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from

0 commit comments

Comments
 (0)