Retrieve resources from a GitHub API endpoint.
var get = require( '@stdlib/_tools/github/get' );Retrieves resources from a GitHub API endpoint.
get( onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}The function accepts the following options:
- protocol: request protocol. Default:
'https'. - hostname: endpoint hostname. Default:
'api.github.com'. - port: endpoint port. Default:
443(https) or80(http). - pathname: resource pathname; e.g.,
/user/repos. Default:'/'. - page: resource page. Default:
1. - last_page: last resource page. If provided, the function will use link headers to resolve all pages starting from
page. Default:1. - per_page: page size. Default:
100. - query: params portion of a query
string; e.g.,beep=boop&a=b. This should not includepageorper_pagequery params. Default:''. - token: GitHub access token.
- accept: media type. Default:
'application/vnd.github.moondragon+json'. - useragent: user agent
string.
To specify a particular resource endpoint, set the pathname option.
var opts = {
'pathname': '/user/repos'
};
get( opts, onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}To authenticate with an endpoint, set the token option.
var opts = {
'token': 'tkjorjk34ek3nj4!'
};
get( opts, onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}By default, the function only requests a single page of results. To resolve multiple pages, set the last_page option.
// Resolves pages 2-5...
var opts = {
'page': 2,
'last_page': 5
};
get( opts, onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}To specify that all pages beginning from page be resolved, set the last_page option to 'last'.
// Resolve all pages...
var opts = {
'last_page': 'last'
};
get( opts, onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}To specify a user agent, set the useragent option.
var opts = {
'useragent': 'hello-github!'
};
get( opts, onResponse );
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}Returns a function which can be repeatedly invoked to retrieve resources from a GitHub API endpoint.
function onResponse( error, data, info ) {
// Check for rate limit info...
if ( info ) {
console.error( 'Limit: %d', info.limit );
console.error( 'Remaining: %d', info.remaining );
console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( JSON.stringify( data ) );
}
}
var opts = {
'pathname': '/user/repos',
'last_page': 'last',
'token': 'tkjorjk34ek3nj4!'
};
var getRepos = get.factory( opts, onResponse );
getRepos();
getRepos();
getRepos();
// ...The method accepts the same options as get() above.
-
If an application-level
erroris encountered while initially querying an endpoint (e.g., no network connection, malformed request, etc), thaterroris returned immediately to the provided callback. -
Response data will either be an
objector an objectarray. If multiple pages are resolved, response data is always an objectarray. -
The
last_pageoption is honored as long as the option value does not exceed the maximum number of available pages. -
Rate limit information includes the following:
- limit: maximum number of requests a consumer is permitted to make per hour.
- remaining: number of remaining requests.
- reset: time at which the current rate limit window resets in UTC seconds.
var get = require( '@stdlib/_tools/github/get' );
var opts = {
'hostname': 'api.github.com',
'pathname': '/user/repos',
'useragent': 'my-unique-agent',
'accept': 'application/vnd.github.moondragon+json',
'token': 'tkjorjk34ek3nj4!',
'last_page': 'last'
};
get( opts, onResponse );
function onResponse( error, data, info ) {
if ( info ) {
console.error( info );
}
if ( error ) {
if ( error instanceof Error ) {
throw error;
}
console.error( error.message );
} else {
console.log( data );
}
}Note: in order to run the example, you will need to obtain an access token and modify the token option accordingly.
Usage: ghget [options]
Options:
-h, --help Print this message.
-V, --version Print the package version.
--protocol proto Request protocol. Default: https.
--hostname host Hostname. Default: api.github.com.
-p, --port port Port. Default: 443 (https) or 80 (http).
--pathname path Resource pathname. Default: '/'.
--token token Github access token.
--accept type Media type. Default: application/vnd.github.v3+json.
--ua, --useragent ua User agent.
--page page Resource page. Default: 1.
--last_page page Last resource page to resolve. Default: 1.
--per_page size Page size. Default: 100.
--qs, --query qs Params portion of a query string.
- In addition to the
tokenoption, the token may also be specified by aGITHUB_TOKENenvironment variable. The command-line option always takes precedence. - Requested resources are written to
stdout. - Rate limit information is written to
stderr.
Setting the access token using the command-line option:
$ DEBUG=* ghget --token <token> --pathname '/user/repos'
# => '[{...},{...},...]'Setting the access token using an environment variable:
$ DEBUG=* GITHUB_TOKEN=<token> ghget --pathname '/user/repos'
# => '[{...},{...},...]'