Based on a subset of hub api features:

• authenticates every request with the user's token;
• exposes both GitHub REST (v3) and GraphQL (v4) APIs;
• offers JSON serialization via parameter flags;
• allows overriding request method;
• allows adding request headers;
• allows printing response headers.

$ gh help api
Makes an authenticated HTTP request to the GitHub API and prints the response.

The <endpoint> argument should either be a path of a GitHub API v3 endpoint, or
"graphql" to access the GitHub API v4.

The default HTTP request method is "GET" normally and "POST" if any parameters
were added. Override the method with '--method'.

Pass one or more '--raw-field' values in "<key>=<value>" format to add
JSON-encoded string parameters to the POST body.

The '--field' flag behaves like '--raw-field' with magic type conversion based
on the format of the value:

- literal values "true", "false", "null", and integer numbers get converted to
  appropriate JSON types;
- if the value starts with "@", the rest of the value is interpreted as a
  filename to read the value from. Pass "-" to read from standard input.

Usage:
  gh api <endpoint> [flags]

Flags:
  -F, --field stringArray       Add a parameter of inferred type
  -H, --header stringArray      Add an additional HTTP request header
  -i, --include                 Include HTTP response headers in the output
  -X, --method string           The HTTP method for the request (default "GET")
  -f, --raw-field stringArray   Add a string parameter

The -X, -F, -H, and -i flags were originally largely modelled after curl, since that's a tool that a lot of command-line users already have experience with. The gh api command is basically curl for GitHub.

Examples:

# print information about the authenticating user
$ gh api user

# pipe the output to `jq` (installed separately) to extract the "name" field
$ gh api user | jq .name

# comment on an issue in `cli/cli`
# note: this is a POST request since we've added parameters
$ gh api repos/cli/cli/issues/909/comments -f body='hello from cli!'

# mark a pull request as ready-for-review
$ gh api -X PATCH repos/cli/cli/pulls/909 -F draft=false

# make a GraphQL request by using the query read from file
$ gh api graphql -F query=@path/to/myquery.graphql

TODO:

• have a design pass
• add support for GraphQL parameters other than query
• serialize parameters to query string if --method=GET
• exit with non-zero status code on non-2xx HTTP responses
• detect GraphQL error responses
• show helpful error when request failed due to insufficient OAuth scopes
• allow special keywords/placeholders for making requests to the current repository?
• enable input of JSON arrays as fields somehow?
• allow input of raw POST body?
• pretty-print response JSON?
• offer an output format alternative to JSON?

Fixes #332