Awesome
gh-got
Convenience wrapper for Got to interact with the GitHub API
Unless you're already using Got, you should probably use GitHub's own @octokit/rest.js or @octokit/graphql.js packages instead.
Install
npm install gh-got
Usage
Instead of:
import got from 'got';
const token = 'foo';
const {body} = await got('https://api.github.com/users/sindresorhus', {
json: true,
headers: {
'accept': 'application/vnd.github.v3+json',
'authorization': `token ${token}`
}
});
console.log(body.login);
//=> 'sindresorhus'
You can do:
import ghGot from 'gh-got';
const {body} = await ghGot('users/sindresorhus', {
context: {
token: 'foo'
}
});
console.log(body.login);
//=> 'sindresorhus'
Or:
import ghGot from 'gh-got';
const {body} = await ghGot('https://api.github.com/users/sindresorhus', {
context: {
token: 'foo'
}
});
console.log(body.login);
//=> 'sindresorhus'
API
Same API as got
, including options, the stream API, aliases, pagination, etc, but with some additional options below.
Errors are improved by using the custom GitHub error messages. Doesn't apply to the stream API.
gh-got
specific options
token
Type: string
GitHub access token.
Can be set globally with the GITHUB_TOKEN
environment variable.
prefixUrl
Type: string
Default: https://api.github.com/
To support GitHub Enterprise.
Can be set globally with the GITHUB_ENDPOINT
environment variable.
body
Type: object
Can be specified as a plain object and will be serialized as JSON with the appropriate headers set.
Rate limit
Responses and errors have a .rateLimit
property with info about the current rate limit. (This is not yet implemented for the stream API)
import ghGot from 'gh-got';
const {rateLimit} = await ghGot('users/sindresorhus');
console.log(rateLimit);
//=> {limit: 5000, remaining: 4899, reset: [Date 2018-12-31T20:45:20.000Z]}
Authorization
Authorization for GitHub uses the following logic:
- If
options.headers.authorization
is passed togh-got
, then this will be used as first preference. - If
options.token
is provided, then theauthorization
header will be set totoken <options.token>
. - If
options.headers.authorization
andoptions.token
are not provided, then theauthorization
header will be set totoken <process.env.GITHUB_TOKEN>
In most cases, this means you can simply set GITHUB_TOKEN
, but it also allows it to be overridden by setting options.token
or options.headers.authorization
explicitly. For example, if authenticating as a GitHub App, you could do the following:
import ghGot from 'gh-got';
const options = {
headers: {
authorization: `Bearer ${jwt}`
}
};
const {body} = await ghGot('app', options);
console.log(body.name);
//=> 'MyApp'
Pagination
See the Got docs.