diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index 889a4876172a..50ffc40e5280 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -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 @@ -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 @@ -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 @@ -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 %} @@ -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. @@ -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: @@ -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. @@ -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. @@ -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 @@ -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) ``` @@ -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 @@ -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 @@ -647,7 +646,7 @@ You can write a JavaScript handler to process the callback. Here's a minimal exa 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: @@ -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. @@ -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 -