Skip to content

Add missing cli parameter to curl command #16506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 72 additions & 74 deletions content/rest/overview/resources-in-the-rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ topics:
- API
---


This describes the resources that make up the official {% data variables.product.product_name %} REST API. If you have any problems or requests, please contact {% data variables.contact.contact_support %}.

## Current version
Expand All @@ -31,7 +30,7 @@ For information about GitHub's GraphQL API, see the [v4 documentation]({% ifvers

## 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
{% 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
Expand Down Expand Up @@ -93,7 +92,7 @@ response illustrates all attributes that are returned by that method.

## Authentication

{% ifversion ghae %} We recommend authenticating to the {% data variables.product.product_name %} REST API by creating an OAuth2 token through the [web application flow](/developers/apps/authorizing-oauth-apps#web-application-flow). {% else %} There are two ways to authenticate through {% data variables.product.product_name %} REST API.{% endif %} Requests that require authentication will return `404 Not Found`, instead of `403 Forbidden`, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.
{% ifversion ghae %} We recommend authenticating to the {% data variables.product.product_name %} REST API by creating an OAuth2 token through the [web application flow](/developers/apps/authorizing-oauth-apps#web-application-flow). {% else %} There are two ways to authenticate through {% data variables.product.product_name %} REST API.{% endif %} Requests that require authentication will return `404 Not Found`, instead of `403 Forbidden`, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.

### Basic authentication

Expand All @@ -113,9 +112,10 @@ Note: GitHub recommends sending OAuth tokens using the Authorization header.

{% endnote %}

Read [more about OAuth2](/apps/building-oauth-apps/). Note that OAuth2 tokens can be acquired using the [web application flow](/developers/apps/authorizing-oauth-apps#web-application-flow) for production applications.
Read [more about OAuth2](/apps/building-oauth-apps/). Note that OAuth2 tokens can be acquired using the [web application flow](/developers/apps/authorizing-oauth-apps#web-application-flow) for production applications.

{% ifversion fpt or ghes or ghec %}

### OAuth2 key/secret

{% data reusables.apps.deprecating_auth_with_query_parameters %}
Expand Down Expand Up @@ -204,65 +204,64 @@ See the guide on "[Using Global Node IDs]({% ifversion ghec%}/free-pro-team@late
There are three possible types of client errors on API calls that
receive request bodies:

1. Sending invalid JSON will result in a `400 Bad Request` response.
1. Sending invalid JSON will result in a `400 Bad Request` response.

HTTP/2 400
Content-Length: 35

{"message":"Problems parsing JSON"}

2. Sending the wrong type of JSON values will result in a `400 Bad
Request` response.
2. Sending the wrong type of JSON values will result in a `400 Bad Request` response.

HTTP/2 400
Content-Length: 40
HTTP/2 400
Content-Length: 40

{"message":"Body should be a JSON object"}
{"message":"Body should be a JSON object"}

3. Sending invalid fields will result in a `422 Unprocessable Entity`
response.
3. Sending invalid fields will result in a `422 Unprocessable Entity`
response.

HTTP/2 422
Content-Length: 149
HTTP/2 422
Content-Length: 149

{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
}
]
}
{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
}
]
}

All error objects have resource and field properties so that your client
can tell what the problem is. There's also an error code to let you
know what is wrong with the field. These are the possible validation error
can tell what the problem is. There's also an error code to let you
know what is wrong with the field. These are the possible validation error
codes:

Error code name | Description
-----------|-----------|
`missing` | A resource does not exist.
`missing_field` | A required field on a resource has not been set.
`invalid` | The formatting of a field is invalid. Review the documentation for more specific information.
`already_exists` | Another resource has the same value as this field. This can happen in resources that must have some unique key (such as label names).
`unprocessable` | The inputs provided were invalid.
| Error code name | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `missing` | A resource does not exist. |
| `missing_field` | A required field on a resource has not been set. |
| `invalid` | The formatting of a field is invalid. Review the documentation for more specific information. |
| `already_exists` | Another resource has the same value as this field. This can happen in resources that must have some unique key (such as label names). |
| `unprocessable` | The inputs provided were invalid. |

Resources may also send custom validation errors (where `code` is `custom`). Custom errors will always have a `message` field describing the error, and most errors will also include a `documentation_url` field pointing to some content that might help you resolve the error.

## HTTP redirects

API v3 uses HTTP redirection where appropriate. Clients should assume that any
request may result in a redirection. Receiving an HTTP redirection is *not* an
request may result in a redirection. Receiving an HTTP redirection is _not_ an
error and clients should follow that redirect. Redirect responses will have a
`Location` header field which contains the URI of the resource to which the
client should repeat the requests.

Status Code | Description
-----------|-----------|
`301` | Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed to the new URI.
`302`, `307` | Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests.
| Status Code | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `301` | Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed to the new URI. |
| `302`, `307` | Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests. |

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

Expand All @@ -271,22 +270,22 @@ Other redirection status codes may be used in accordance with the HTTP 1.1 spec.
Where possible, API v3 strives to use appropriate HTTP verbs for each
action.

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.
| 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
resources. These are meant to provide explicit URLs so that proper API clients
don't need to construct URLs on their own. It is highly recommended that API
clients use these. Doing so will make future upgrades of the API easier for
developers. All URLs are expected to be proper [RFC 6570][rfc] URI templates.
resources. These are meant to provide explicit URLs so that proper API clients
don't need to construct URLs on their own. It is highly recommended that API
clients use these. Doing so will make future upgrades of the API easier for
developers. All URLs are expected to be proper [RFC 6570][rfc] URI templates.

You can then expand these templates using something like the [uri_template][uri]
gem:
Expand All @@ -307,7 +306,7 @@ gem:
## Pagination

Requests that return multiple items will be paginated to 30 items by
default. You can specify further pages with the `page` parameter. For some
default. You can specify further pages with the `page` parameter. For some
resources, you can also set a custom page size up to 100 with the `per_page` parameter.
Note that for technical reasons not all endpoints respect the `per_page` parameter,
see [events](/rest/reference/activity#events) for example.
Expand Down Expand Up @@ -348,16 +347,16 @@ This `Link` response header contains one or more [Hypermedia](/rest#hypermedia)

The possible `rel` values are:

Name | Description
-----------|-----------|
`next` |The link relation for the immediate next page of results.
`last` |The link relation for the last page of results.
`first` |The link relation for the first page of results.
`prev` |The link relation for the immediate previous page of results.
| Name | Description |
| ------- | ------------------------------------------------------------- |
| `next` | The link relation for the immediate next page of results. |
| `last` | The link relation for the last page of results. |
| `first` | The link relation for the first page of results. |
| `prev` | The link relation for the immediate previous page of results. |

## Rate limiting

Different types of API requests to {% data variables.product.product_location %} are subject to different rate limits.
Different types of API requests to {% data variables.product.product_location %} are subject to different rate limits.

Additionally, the Search API has dedicated limits. For more information, see "[Search](/rest/reference/search#rate-limit)" in the REST API documentation.

Expand Down Expand Up @@ -387,7 +386,7 @@ For unauthenticated requests, the rate limit allows for up to 60 requests per ho

### Requests from GitHub Apps

Requests from a GitHub App may be either user-to-server or server-to-server requests. For more information about rate limits for GitHub Apps, see "[Rate limits for GitHub Apps](/developers/apps/building-github-apps/rate-limits-for-github-apps)."
Requests from a GitHub App may be either user-to-server or server-to-server requests. For more information about rate limits for GitHub Apps, see "[Rate limits for GitHub Apps](/developers/apps/building-github-apps/rate-limits-for-github-apps)."

### Requests from GitHub Actions

Expand Down Expand Up @@ -416,15 +415,15 @@ $ curl -I {% data variables.product.api_url_pre %}/users/octocat
> x-ratelimit-reset: 1372700873
```

Header Name | Description
-----------|-----------|
`x-ratelimit-limit` | The maximum number of requests you're permitted to make per hour.
`x-ratelimit-remaining` | The number of requests remaining in the current rate limit window.
`x-ratelimit-reset` | The time at which the current rate limit window resets in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time).
| Header Name | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `x-ratelimit-limit` | The maximum number of requests you're permitted to make per hour. |
| `x-ratelimit-remaining` | The number of requests remaining in the current rate limit window. |
| `x-ratelimit-reset` | The time at which the current rate limit window resets in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time). |

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

``` javascript
```javascript
new Date(1372700873 * 1000)
// => Mon Jul 01 2013 13:47:53 GMT-0400 (EDT)
```
Expand All @@ -449,7 +448,7 @@ If you exceed the rate limit, an error response returns:
If your OAuth App needs to make unauthenticated calls with a higher rate limit, you can pass your app's client ID and secret before the endpoint route.

```shell
$ curl -u my_client_id:my_client_secret {% data variables.product.api_url_pre %}/user/repos
$ curl -u my_client_id:my_client_secret -I {% data variables.product.api_url_pre %}/user/repos
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
Expand Down Expand Up @@ -598,9 +597,9 @@ Access-Control-Max-Age: 86400
## JSON-P callbacks

You can send a `?callback` parameter to any GET call to have the results
wrapped in a JSON function. This is typically used when browsers want
wrapped in a JSON function. This is typically used when browsers want
to embed {% data variables.product.product_name %} content in web pages by getting around cross domain
issues. The response includes the same data output as the regular API,
issues. The response includes the same data output as the regular API,
plus the relevant HTTP Header information.

```shell
Expand Down Expand Up @@ -647,7 +646,7 @@ You can write a JavaScript handler to process the callback. Here's a minimal exa
</html>

All of the headers are the same String value as the HTTP Headers with one
notable exception: Link. Link headers are pre-parsed for you and come
notable exception: Link. Link headers are pre-parsed for you and come
through as an array of `[url, options]` tuples.

A link that looks like this:
Expand Down Expand Up @@ -680,10 +679,10 @@ A link that looks like this:

Some requests that create new data, such as creating a new commit, allow you to provide time zone information when specifying or generating timestamps. We apply the following rules, in order of priority, to determine timezone information for such API calls.

* [Explicitly providing an ISO 8601 timestamp with timezone information](#explicitly-providing-an-iso-8601-timestamp-with-timezone-information)
* [Using the `Time-Zone` header](#using-the-time-zone-header)
* [Using the last known timezone for the user](#using-the-last-known-timezone-for-the-user)
* [Defaulting to UTC without other timezone information](#defaulting-to-utc-without-other-timezone-information)
- [Explicitly providing an ISO 8601 timestamp with timezone information](#explicitly-providing-an-iso-8601-timestamp-with-timezone-information)
- [Using the `Time-Zone` header](#using-the-time-zone-header)
- [Using the last known timezone for the user](#using-the-last-known-timezone-for-the-user)
- [Defaulting to UTC without other timezone information](#defaulting-to-utc-without-other-timezone-information)

Note that these rules apply only to data passed to the API, not to data returned by the API. As mentioned in "[Schema](#schema)," timestamps returned by the API are in UTC time, ISO 8601 format.

Expand Down Expand Up @@ -712,4 +711,3 @@ If no `Time-Zone` header is specified and you make an authenticated call to the
If the steps above don't result in any information, we use UTC as the timezone to create the git commit.

[pagination-guide]: /guides/traversing-with-pagination