Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonschlinkert/github-base
Simple, opinionated node.js interface for creating basic apps with the GitHub API.
https://github.com/jonschlinkert/github-base
api axios get github got javascript needle node request url
Last synced: 13 days ago
JSON representation
Simple, opinionated node.js interface for creating basic apps with the GitHub API.
- Host: GitHub
- URL: https://github.com/jonschlinkert/github-base
- Owner: jonschlinkert
- License: mit
- Created: 2015-03-31T08:34:10.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-08-14T16:45:42.000Z (about 6 years ago)
- Last Synced: 2024-10-04T11:58:46.338Z (about 1 month ago)
- Topics: api, axios, get, github, got, javascript, needle, node, request, url
- Language: JavaScript
- Homepage: http://jonschlinkert.github.io/github-base
- Size: 102 KB
- Stars: 60
- Watchers: 5
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# github-base [](https://www.npmjs.com/package/github-base) [](https://npmjs.org/package/github-base) [](https://npmjs.org/package/github-base) [](https://travis-ci.org/jonschlinkert/github-base) [](https://ci.appveyor.com/project/jonschlinkert/github-base)
> Low-level methods for working with the GitHub API in node.js/JavaScript.
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
## Table of Contents
Details
- [Install](#install)
- [Heads up!](#heads-up)
- [Why github-base, instead of...?](#why-github-base-instead-of)
- [Usage](#usage)
- [API](#api)
* [GitHub](#github)
* [.request](#request)
* [.get](#get)
* [.delete](#delete)
* [.patch](#patch)
* [.post](#post)
* [.put](#put)
* [.paged](#paged)
* [.use](#use)
- [Authentication](#authentication)
- [Paths and placeholders](#paths-and-placeholders)
- [Options](#options)
* [options.query](#optionsquery)
- [About](#about)
* [Related projects](#related-projects)
* [Contributors](#contributors)
* [Author](#author)
* [License](#license)
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save github-base
```
## Heads up!
As of v1.0, the API is 100% promise based, callbacks are no longer supported. Please see the [API documentation](#API) and [release history](changelog.md) for more details.
## Why github-base, instead of...?
Every other GitHub API library we found either had a [huge dependency tree](https://github.com/sindresorhus/gh-got), tries to be [everything to everyone](https://github.com/michael/github/blob/master/package.json#L45-L56), was [too bloated with boilerplace code](https://github.com/mikedeboer/node-github/tree/master/templates), 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](#request): the base handler all of the GitHub HTTP verbs: `GET`, `PUT`, `POST`, `DELETE`, `PATCH`
* [.get](#get): proxy for `.request('GET', path, options, cb)`
* [.delete](#delete): proxy for `.request('DELETE', path, options, cb)`
* [.patch](#patch): proxy for `.request('PATCH', path, options, cb)`
* [.post](#post): proxy for `.request('POST', path, options, cb)`
* [.put](#put): proxy for `.request('PUT', path, options, cb)`
* [.paged](#paged): recursively makes `GET` requests until all pages have been retrieved.
Jump to the [API section](#API) for more details.
## Usage
Add github-base to your node.js/JavaScript project with the following line of code:
```js
const GitHub = require('github-base');
```
**Example usage**
Recursively `GET` all pages of gists for a user:
```js
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)_.
### [GitHub](index.js#L18)
Create an instance of `GitHub` with the given options.
**Params**
* `options` **{Object}**
**Example**
```js
const GitHub = require('github-base');
const github = new GitHub([options]);
```
### [.request](index.js#L42)
Uses [needle](https://github.com/tomas/needle) to make a request to the GitHub API. Supports the following verbs: `GET`, `PUT`, `POST`, `PATCH`, and `DELETE`. Takes a callback or returns a promise.
**Params**
* `method` **{String}**: The http VERB to use
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// list all orgs for the authenticated user
const auth = require('./local-private-auth-info');
const github = new GitHub(auth);
github.request('GET', '/user/orgs')
.then(res => console.log(res.body));
```
### [.get](index.js#L64)
Make a `GET` request to the GitHub API.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// get a list of orgs for the authenticated user
github.get('/user/orgs')
.then(res => console.log(res.body));
// get gists for the authenticated user
github.get('/gists')
.then(res => console.log(res.body));
```
### [.delete](index.js#L84)
Make a `DELETE` request to the GitHub API.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// un-follow someone
github.delete('/user/following/:some_username', { some_username: 'whatever' })
.then(res => {
console.log('RESPONSE:', res);
});
```
### [.patch](index.js#L106)
Make a `PATCH` request to the GitHub API.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// update a gist
const fs = require('fs');
const options = { files: { 'readme.md': { content: fs.readFileSync('README.md', 'utf8') } } };
github.patch('/gists/bd139161a425896f35f8', options)
.then(res => {
console.log('RESPONSE:', res);
});
```
### [.post](index.js#L126)
Make a `POST` request to the GitHub API.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// create a new repository
github.post('/user/repos', { name: 'new-repo-name' })
.then(res => {
console.log('RESPONSE:', res);
});
```
### [.put](index.js#L146)
Make a `PUT` request to the GitHub API.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// follow someone
github.put('/user/following/jonschlinkert')
.then(res => {
console.log('RESPONSE:', res);
});
```
### [.paged](index.js#L165)
Recursively make GET requests until all pages of records are returned.
**Params**
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).
**Example**
```js
// get all repos for the authenticated user
github.paged('/user/repos?type=all&per_page=1000&sort=updated')
.then(res => console.log(res.pages))
.catch(console.error)
```
### .use
Register plugins with [use](https://github.com/jonschlinkert/use).
```js
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](#options).
```js
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:
```js
const github = new GitHub();
const options = { user: 'jonschlinkert', repo: 'github-base', subscribed: true };
github.put('/repos/:user/:repo/subscription', options);
```
Expands to:
```js
'/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**
```js
// 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](#get) and [paged](#paged) requests, `undefined` for all other requests.
Pass an object to stringify and append to the URL using the `.stringify` method from [qs](https://github.com/ljharb/qs).
**Examples**
```js
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:
```js
github.paged('/users/:user/gists?per_page=30', { user: 'doowb' })
.then(res => {
console.log(res.pages);
});
```
## About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
Building docs
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
### Related projects
You might also be interested in these projects:
* [gists](https://www.npmjs.com/package/gists): Methods for working with the GitHub Gist API. Node.js/JavaScript | [homepage](https://github.com/jonschlinkert/gists "Methods for working with the GitHub Gist API. Node.js/JavaScript")
* [github-contributors](https://www.npmjs.com/package/github-contributors): Generate a markdown or JSON list of contributors for a project using the GitHub API. | [homepage](https://github.com/jonschlinkert/github-contributors "Generate a markdown or JSON list of contributors for a project using the GitHub API.")
* [repos](https://www.npmjs.com/package/repos): List all repositories for one or more users or orgs. | [homepage](https://github.com/jonschlinkert/repos "List all repositories for one or more users or orgs.")
* [topics](https://www.npmjs.com/package/topics): Get and update GitHub repository topics. | [homepage](https://github.com/jonschlinkert/topics "Get and update GitHub repository topics.")
### Contributors
| **Commits** | **Contributor** |
| --- | --- |
| 40 | [jonschlinkert](https://github.com/jonschlinkert) |
| 10 | [doowb](https://github.com/doowb) |
| 7 | [olstenlarck](https://github.com/olstenlarck) |
### Author
**Jon Schlinkert**
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
### License
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on August 14, 2018._