# curl

## Introduction

An introduction to curl using GitHub's API

## The Basics

Makes a basic GET request to the specifed URI

```
curl https://api.github.com/users/caspyin
```

Includes HTTP-Header information in the output

```
curl --include https://api.github.com/users/caspyin
```

Pass user credential to basic auth to access protected resources like a users starred gists, or private info associated with their profile

```
curl --user "caspyin:PASSWD" https://api.github.com/gists/starred
curl --user "caspyin:PASSWD" https://api.github.com/users/caspyin
```

Passing just the username without the colon (`:`) will cause you to be prompted for your account password. This avoids having your password in your command line history

```
curl --user "caspyin" https://api.github.com/users/caspyin
```

### POST

Use the `--request` (`-X`) flag along with `--data` (`-d`) to POST data

```
curl --user "caspyin" --request POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}' https://api.github.com/gists

curl --user "caspyin" -X POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}' https://api.github.com/gists
```

Of course `--data` implies POST so you don't have to also specify the `--request` flag

```
curl --user "caspyin" --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}' https://api.github.com/gists
```

Here is an example that uses the old GitHub API (v2). You can use multiple `--data` flags

```
curl --data "login=caspyin" --data "token=TOKEN" https://github.com/api/v2/json/user/show/caspyin
```

The post data gets combined into one so you can also just combine them yourself into a single `--data` flag

```
curl --data "login=caspyin&token=TOKEN" https://github.com/api/v2/json/user/show/caspyin
```

You can tell curl to read from a file (`@`) to POST data

```
curl --user "caspyin" --data @data.txt https://api.github.com/gists 
```

Or it can read from STDIN (`@-`)

```
curl --user "caspyin" --data @- https://api.github.com/gists
{
  "description":"Test",
  "public":false,
  "files": {
    "file1.txt": {
      "content":"Demo"
    }
  }
}
end with ctrl+d
```

#### Headers

Often when POSTing data you'll need to add headers for things like auth tokens or setting the content type. You can set a header using `-H`.

```
curl -H "Content-Type: application/json" -H "authToken: 349ab29a-xtab-423b-a5hc-5623bc39b8c8" --data '{}' https://api.example.com/endpoint
```

#### Dealing with HTTPS

If an API doens't have an SSL cert but is using HTTPS you can tell curl to ignore the security by using `--insecure`. Be warned this is a very **"insecure"** thing to do and is only listed here for "educational purposes".

```
curl --insecure https://api.example.com/endpoint
```

For my own reference mostly, here is where I first learned about using `--insecure` <https://github.com/wayneeseguin/rvm/issues/1684>

## OAuth

The first thing to know is that your API Token (found in <https://github.com/settings/admin>) is not the same token used by OAuth. They are different tokens and you will need to generate an OAuth token to be authorized.

Follow the API's instructions at <http://developer.github.com/v3/oauth/> under the sections "Non-Web Application Flow" and "Create a new authorization" to become authorized.

Note: Use Basic Auth once to create an OAuth2 token <http://developer.github.com/v3/oauth/#oauth-authorizations-api>

```
curl https://api.github.com/authorizations \
--user "caspyin" \
--data '{"scopes":["gist"],"note":"Demo"}'
```

This will prompt you for your GitHub password and return your OAuth token in the response. It will also create a new Authorized application in your account settings <https://github.com/settings/applications>

Now that you have the OAuth token there are two ways to use the token to make requests that require authentication (replace "OAUTH-TOKEN" with your actual token)

```
curl https://api.github.com/gists/starred?access_token=OAUTH-TOKEN
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/gists/starred
```

List the authorizations you already have

```
curl --user "caspyin" https://api.github.com/authorizations
```

## Resources

* HTTParty - Ruby library that makes it easy to create HTTP requests <https://github.com/jnunemaker/httparty>
* Hurl IT - An open source web application to play with curl options <http://hurl.it>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://chadboyce.gitbook.io/notes/curl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.