Resources in the REST API (Developing GitHub Apps)

Resources in the REST API

Learn how to navigate the resources provided by the GitHub API.

This describes the resources that make up the official GitHub REST API.

Current Version
By default, all requests to https://api.github.com receive the v3 version of the REST API. We encourage you to explicitly request this version via the ‘Accept’ header.
```
Accept: application/vnd.github.v3+json
```
Schema
- All API access is over HTTPS.
- The API is accessed from https://api.github.com.
- All data is sent and received as JSON.
- All timestamps return in ISO 8601 format:
```
YYYY-MM-DDTHH:MM:SSZ
```
- 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.
  
  Example: When you get a list of repositories, you get the summary representation of each repository.
```
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.
  
  Example: When you get an individual repository, you get the detailed representation of the repository.
```
GET /repos/octokit/octokit.rb
```
Authentication
There are two ways to authenticate through GitHub REST API.
- Basic authentication
```
$ curl -u "username" https://api.github.com
```
- OAuth2 token (sent in a header)
```
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
```
  OAuth2 tokens can be acquired using the web application flow for production applications.
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:
```
$ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"
```
- 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’:
```
$ curl -i -u username -d '{"scopes":["public_repo"]}' https://api.github.com/authorizations
```
Root Endpoint
You can issue a ‘GET’ request to the root endpoint to get all the endpoint categories that the REST API supports:
```
$ curl -u username:token https://api.github.com
```
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 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 Codes
  
  301
  
  Permanent redirection.
  
  302
  
  Temporary redirection.
  
  307
  
  Ditto
HTTP Verbs
Where possible, API v3 strives to use appropriate HTTP verbs for each action.
- Verbs
  
  ‘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.
  
  ‘PUT’
  
  Used for replacing resources or collections.
  
  ‘DELETE’
  
  Used for deleting resources.
Pagination
Requests that return multiple items will be paginated to 30 items by default.
- parameters
  
  ‘page’
  
  You can specify further pages with the ‘page’ parameter.
  
  ‘per_page’
  
  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’ for example.
```
$ curl 'https://api.github.com/user/repos?page=2&per_page=100'
```
- cursor-based pagination
  - Some endpoints use cursor-based pagination.
  - A cursor is a string that points to a location in the result set.
  - With cursor-based pagination, there is no fixed concept of "pages" in the result set, so you can’t navigate to a specific page.
  - Instead, you can traverse the results by using the before or after parameters.
  - See guide on Traversing with Pagination.
Link Header
- Link Header
Rate Limiting
- Rate Limiting
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 GitHub username, or
- the name of your application, for the ‘User-Agent’ header value.
- This allows us to contact you if there are problems.
```
User-Agent: Awesome-Octocat-App
```
cURL sends a valid ‘User-Agent’ header by default
Conditional requests
Most responses return an ‘ETag’ header.

Many responses also return a ‘Last-Modified’ header.

You can use the values of these headers to make subsequent requests to those resources using the:
- ‘If-None-Match’ and
```
$ curl -i https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
```
- ‘If-Modified-Since’
```
$ curl -i https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
```
headers, respectively.

If the resource has not changed, the server will return a ‘304 Not Modified’.

Making a conditional request and receiving a 304 response does not count against your ‘Rate Limit’, so we encourage you to use it whenever possible.
Cross origin resource sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.
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 to embed GitHub content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.
- JSON-P Callbacks