gist-oauth

• A small library (< 4kb when minimized and gzipped) through which we can call all Gist APIs provided by github.
• If it is an express application, It is recommended to use with github-oauth-express for OAuth. A small < 6kb package. (A five min simple implementation for getting github Auth token)
• Or else you can use your own way of getting OAuth Token from github. As authToken is essential for accessing user specific datas.

npm install --save github-oauth-express gist-oauth

Contents

• Initial Setup
• APIs
  • List a user's gists
  • List all public gists
  • List starred gists
  • Get a single gist
  • Get a specific revision of a gist
  • Create a gist
  • Edit a gist
  • List gist commits
  • Star a gist
  • Unstar a gist
  • Check if a gist is starred
  • Fork a gist
  • List gist forks
  • Delete a gist

Initial Setup

const express = require('express');
const app = express();

const githubAPI = require('github-oauth-express');
const gistOAuth = require('gist-oauth');

// YOUR EXPRESS APPLICATION

githubAPI(
  app, // Send your app instance to get OAuth Access
  {
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectURL: '/oauth-call'
  }
)
  .then(authToken => {
    console.log('Obtained Auth token');
    const gistAPI = gistOauth(authToken);

    // gistAPI provides all Gist's API
    // For Eg:
    gistAPI
      .getGists() // returns all public and secret gists of that user.
      .then(res => console.log('res:', res))
      .catch(err => console.log('err:', err));
  })
  .catch(err => console.log(err));

APIs

• Every API returns a promise. Results are obtained in resolved object. So if any error occured during the process then it will be rejected.

List a user's gists

Parameters

• since - optional This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

gistAPI
  .getGists(since) // returns all public and secret gists of that user.
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

List all public gists

Parameters

• since - optional This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

gistAPI
  .getPublic(since)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

List starred gists

Parameters

• since - optional This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

gistAPI
  .getStarred(since)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Get a single gist

Parameters

• gistId - Particular ID of the gist obtained in above APIs.

gistAPI
  .getGist(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Get a specific revision of a gist

Parameters

• gistId - Particular ID of the gist obtained in above APIs.
• sha - Particular file's SHA

gistAPI
  .getSpecificRevision(gistId, sha)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Create a gist

Parameters

• files (object) - List of files. They must be of format like

  const files = {
    'file1.txt': {
      content: 'Entire file contents'
    },
    'file2.py': {
      content: "print('Hello world')"
    }
  };

• description (string) - A small description about the gist.

• isPublic (boolean) - true if public and false to create a secret gist.

gistAPI
  .create(files, description, isPublic)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Edit a gist

Parameters

• gistId (string) - Gist Id of the particular gist.

• files (object) - Files of format

  const files = {
    'file1.txt': {
      content: 'Entire file contents'
    },
    'file2.py': {
      content: "print('Hello world')"
    }
  };

  with edited contents.

• description (string) - Updated description

gistAPI
  .edit(gistId, files, description)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

List gist commits

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .getCommitsList(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Star a gist

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .starGist(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response - If done - Just resolves, else rejects the promise.

Unstar a gist

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .unStarGist(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response - If done - Just resolves, else rejects the promise.

Check if a gist is starred

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .isGistStarred(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response - true if starred. false if unstarred.

Fork a gist

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .forkGist(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

List gist forks

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .getForksList(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response

Delete a gist

Parameters

• gistId (string) - Gist Id of the particular gist.

gistAPI
  .deleteGist(gistId)
  .then(res => console.log('res:', res))
  .catch(err => console.log('err:', err));

Response - If done - Just resolves, else rejects the promise.

For all API Responses refer Gist Github API reference.