Skip to content

Latest commit

 

History

History
144 lines (96 loc) · 3.96 KB

.verb.md

File metadata and controls

144 lines (96 loc) · 3.96 KB
Raw

Heads up!

As of v1.0, the API is 100% promise based, callbacks are no longer supported. Please see the API documentation and release history for more details.

Why github-base, instead of...?

Every other GitHub API library we found either had a huge dependency tree, tries to be everything to everyone, was too bloated with boilerplace code, was too opinionated, or was not maintained.

We created github-base to provide low-level support for a handful of HTTP verbs for creating higher-level libraries:

  • .request: the base handler all of the GitHub HTTP verbs: GET, PUT, POST, DELETE, PATCH
  • .get: proxy for .request('GET', path, options, cb)
  • .delete: proxy for .request('DELETE', path, options, cb)
  • .patch: proxy for .request('PATCH', path, options, cb)
  • .post: proxy for .request('POST', path, options, cb)
  • .put: proxy for .request('PUT', path, options, cb)
  • .paged: recursively makes GET requests until all pages have been retrieved.

Jump to the API section for more details.

Usage

Add github-base to your node.js/JavaScript project with the following line of code:

const GitHub = require('{%= name %}');

Example usage

Recursively GET all pages of gists for a user:

const github = new GitHub({ /* options */ });
const owner = 'jonschlinkert';

github.paged(`/users/${owner}/gists`)
  .then(res => console.log(res))
  .catch(console.error);

API

(All request methods take a callback, or return a promise if a callback isn't passed as the last argument).

{%= apidocs("index.js") %}

.use

Register plugins with [use][].

const github = new GitHub();

github.use(function() {
  // do stuff with the github-base instance
});

Authentication

There are a few ways to authenticate, all of them require info to be passed on the options.

const github = new GitHub({
  username: YOUR_USERNAME,
  password: YOUR_PASSWORD,
});

// or 
const github = new GitHub({
  token: YOUR_TOKEN
});

// or 
const github = new GitHub({
  bearer: YOUR_JSON_WEB_TOKEN
});

Paths and placeholders

Deprecated: Since es2015 templates make this feature less useful, we plan to remove it in a future release.

Paths are similar to router paths, where placeholders in the given string are replaced with values from the options. For instance, the path in the following example:

const github = new GitHub();
const options = { user: 'jonschlinkert', repo: 'github-base', subscribed: true };

github.put('/repos/:user/:repo/subscription', options);

Expands to:

'/repos/jonschlinkert/github-base/subscription'

Placeholder names are also arbitrary, you can make them whatever you want as long as all placeholder names can be resolved using values defined on the options.

Options

Options may be passed to the constructor when instantiating, and/or set on the instance directly, and/or passed to any of the methods.

Examples

// pass to constructor
const github = new GitHub({ user: 'doowb' });

// and/or directly set on instance options
github.options.user = 'doowb';

// and/or pass to a method
github.get('/users/:user/gists', { user: 'doowb' })

options.query

Type: object

Default: { per_page: 100 } for get and paged requests, undefined for all other requests.

Pass an object to stringify and append to the URL using the .stringify method from [qs][].

Examples

github.paged('/users/:user/gists', { user: 'doowb', query: { per_page: 30 } })
  .then(res => {
    console.log(res.pages);
  });

You can also manually append the query string:

github.paged('/users/:user/gists?per_page=30', { user: 'doowb' })
  .then(res => {
    console.log(res.pages);
  });