Project:Sandbox

Getting Started
Let’s walk through core API concepts as we tackle some everyday use cases.
 * Overview
 * Authentication
 * Repositories
 * Issues
 * Conditional requests

Overview
Most applications will use an existing wrapper library in the language of your choice, but it’s important to familiarize yourself with the underlying API HTTP methods first.

There’s no easier way to kick the tires than through cURL.

Hello World
Let’s start by testing our setup. Open up a command prompt and enter the following command (without the  ): $ curl https://api.github.com/zen Keep it logically awesome. The response will be a random selection from our design philosophies.

Next, let’s   Chris Wanstrath’s GitHub profile: $ curl https://api.github.com/users/defunkt {  "login": "defunkt", "id": 2, "url": "https://api.github.com/users/defunkt", "html_url": "https://github.com/defunkt", ... } Mmmmm, tastes like JSON. Let’s add the   flag to include headers: $ curl -i https://api.github.com/users/defunkt HTTP/1.1 200 OK Server: GitHub.com Date: Sun, 11 Nov 2012 18:43:28 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6" X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Reset: 1352660008 X-GitHub-Media-Type: github.v3 Vary: Accept Cache-Control: public, max-age=60, s-maxage=60 X-Content-Type-Options: nosniff Content-Length: 692 Last-Modified: Tue, 30 Oct 2012 18:58:42 GMT {  "login": "defunkt", "id": 2, "url": "https://api.github.com/users/defunkt", "html_url": "https://github.com/defunkt", ... } There are a few interesting bits in the response headers. As expected, the   is .
 * 1) GET /users/defunkt

Any headers beginning with   are custom headers, and are not included in the HTTP spec. Let’s take a look at a few of them:
 * has a value of  . This lets us know the media type for the response. Media types have helped us version our output in API v3. We’ll talk more about that later.
 * Take note of the   and   headers. This pair of headers indicate how many requests a client can make in a rolling time period (typically an hour) and how many of those requests the client has already spent.

Authentication
Unauthenticated clients can make 60 requests per hour. To get more, we’ll need to  authenticate. In fact, doing anything interesting with the GitHub API requires authentication.

Basic
The easiest way to authenticate with the GitHub API is by simply using your GitHub username and password via Basic Authentication. $ curl -i -u  https://api.github.com/users/defunkt Enter host password for user '': The   flag sets the username, and cURL will prompt you for the password. You can use   to avoid the prompt, but this leaves your password in shell history and isn’t recommended. When authenticating, you should see your rate limit bumped to 5,000 requests an hour, as indicated in the   header.

In addition to just getting more calls per hour, authentication is the key to reading and writing private information via the API.

Two-factor authentication
If you have two-factor authentication enabled, the API will return a   error code for the above request (and every other API request): $ curl -i -u  https://api.github.com/users/defunkt Enter host password for user '': HTTP/1.1 401 Unauthorized X-GitHub-OTP: required; :2fa-type {  "message": "Must specify two-factor authentication OTP code.", "documentation_url": "https://developer.github.com/v3/auth#working-with-two-factor-authentication" } The easiest way to get around that error is to create an OAuth token and use OAuth authentication instead of Basic Authentication. See the OAuth section below for more information.

Get your own user profile
When properly authenticated, you can take advantage of the permissions associated with your GitHub account. For example, try getting your own user profile: $ curl -i -u  https://api.github.com/user {  ...   "plan": { "space": 2516582, "collaborators": 10, "private_repos": 20, "name": "medium" }  ... } This time, in addition to the same set of public information we retrieved for @defunkt earlier, you should also see the non-public information for your user profile. For example, you’ll see a  object in the response which gives details about the GitHub plan for the account.

OAuth
While convenient, Basic Authentication isn’t ideal because you shouldn’t give your GitHub username and password to anyone. Applications that need to read or write private information using the API on behalf of another user should use OAuth.

Instead of usernames and passwords, OAuth uses  tokens. Tokens provide two big features: Normally, tokens are created via a web flow. An application sends users to GitHub to log in. GitHub then presents a dialog indicating the name of the app, as well as the level of access the app has once it’s authorized by the user. After a user authorizes access, GitHub redirects the user back to the application:
 * Revokable access : users can revoke authorization to third party apps at any time
 * Limited access : users can review the specific access that a token will provide before authorizing a third party app

However, you don’t need to set up the entire web flow to begin working with OAuth tokens. An easier way to get a token is to create a  personal access token  via your Application settings page:

Also, the  Authorizations API  makes it simple to use Basic Authentication to create an OAuth token. Try pasting and running the following command: $ curl -i -u  -d '{"scopes": ["repo", "user"], "note": "getting-started"}' \ https://api.github.com/authorizations HTTP/1.1 201 Created Location: https://api.github.com/authorizations/2 Content-Length: 384 {  "scopes": [ "repo", "user" ],  "token": "5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4", "updated_at": "2012-11-14T14:04:24Z", "url": "https://api.github.com/authorizations/2", "app": { "url": "https://developer.github.com/v3/oauth/#oauth-authorizations-api", "name": "GitHub API" },  "created_at": "2012-11-14T14:04:24Z", "note_url": null, "id": 2, "note": "getting-started" } There’s a lot going on in this one little call, so let’s break it down. First, the   flag indicates we’re doing a , using the   content type (as opposed to  ). All   requests to the GitHub API should be in JSON.

Next, let’s look at the   we’re sending over in this call. When creating a new token, we include an optional array of  scopes, or access levels, that indicate what information this token can access. In this case, we’re setting up the token with  repo  access, which grants access to read and write to public and private repositories, and  user  scope, which grants read and write access to public and private user profile data. See the scopes docs for a full list of scopes. You should  only  request scopes that your application actually needs, in order to not frighten users with potentially invasive actions. The   status code tells us that the call was successful, and the JSON returned contains the details of our new OAuth token.

If you have two-factor authentication enabled, the API will return the previously described   error code for the above request. You can get around that error by providing a 2FA OTP code in the X-GitHub-OTP request header: $ curl -i -u  -H "X-GitHub-OTP: " \ -d '{"scopes": ["repo", "user"], "note": "getting-started"}' \ https://api.github.com/authorizations