New hub api command for making GitHub API requests

[mislav]

Usage: hub api [-t] [-X <METHOD>] [--cache <TTL>] <ENDPOINT> [-F <KEY-VALUE>]

Goals:

• provide a low-level interface to the GitHub API that empowers GitHub users to automate their workflows via shell scripts
• close many outstanding feature requests in this repository that are unlikely to be implemented in hub core in the near future, but which can be easily implemented as a simple shell script using hub api

Features:

• make arbitrary HTTP requests to the GitHub API
• serialize GET data into query string
• serialize POST/PUT data as JSON
• read data to serialize from a file or standard input
• parse response JSON into line-based output
• cache sucessful responses
• replace {owner} and {repo} placeholders with values from current repository

The above abilities also make it possible to make GraphQL queries, since that simply involves encoding/decoding JSON from the /graphql endpoint.

Examples:

# fetch information about the currently authenticated user as JSON
$ hub api user

# list user repositories as line-based output
$ hub api --flat users/octocat/repos

# post a comment to issue #23 of the current repository
$ hub api repos/{owner}/{repo}/issues/23/comments --raw-field "body=Nice job!"

# perform a GraphQL query read from a file
$ hub api graphql -F query=@path/to/myquery.graphql

[mislav]

Real-world usage example in bash:

# Usage: search [-<LIMIT>] <SEARCH-TERM> [<PAGINATION-CURSOR>]
search() {
  local args=()
  if [ "${1#-}" -gt 0 ] 2>/dev/null; then
    args+=(-F n="${1#-}")
    shift 1
  fi
  args+=(-f q="${1?}")
  [ $# -ge 2 ] && args+=(-f after="${2?}")

  hub api -t --cache 3600 graphql "${args[@]}" -f query='
    query($q: String!, $n: Int = 10, $after: String) {
      search(query: $q, type: REPOSITORY, first: $n, after: $after) {
        edges {
          node {
            ...on Repository {
              nameWithOwner
              stargazers {
                totalCount
              }
            }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  '
}

$ search -3 "rollup plugin"
.data.search.edges.[0].node.nameWithOwner       rollup/rollup-plugin-commonjs
.data.search.edges.[0].node.stargazers.totalCount       360
.data.search.edges.[1].node.nameWithOwner       vuejs/rollup-plugin-vue
.data.search.edges.[1].node.stargazers.totalCount       453
.data.search.edges.[2].node.nameWithOwner       rollup/rollup-plugin-node-resolve
.data.search.edges.[2].node.stargazers.totalCount       319
.data.search.pageInfo.hasNextPage       true
.data.search.pageInfo.endCursor Y3Vyc29yOjM=

$ search -3 "rollup plugin" Y3Vyc29yOjM=
.data.search.edges.[0].node.nameWithOwner       rollup/rollup-plugin-babel
.data.search.edges.[0].node.stargazers.totalCount       527
.data.search.edges.[1].node.nameWithOwner       egoist/rollup-plugin-postcss
.data.search.edges.[1].node.stargazers.totalCount       222
.data.search.edges.[2].node.nameWithOwner       rollup/rollup-plugin-typescript
.data.search.edges.[2].node.stargazers.totalCount       203
.data.search.pageInfo.hasNextPage       true
.data.search.pageInfo.endCursor Y3Vyc29yOjY=