github-api

Github.js

Github.js provides a minimal higher-level wrapper around Github's API. It was concieved in the context of Prose, a content editor for GitHub.

Docs

Read the docs

Installation

Github.js is available from npm or (soon) cdnjs.

npm install github-api

## Compatibility Github.js is tested on Node:

• 0.10
• 0.12
• 4.x
• 5.x

GitHub Tools

The team behind Github.js has created a whole organization, called GitHub Tools, dedicated to GitHub and its API. In the near future this repository could be moved under the GitHub Tools organization as well. In the meantime, we recommend you to take a look at other projects of the organization.

Samples

/*
   Data can be retrieved from the API either using callbacks (as in versions < 1.0)
   or using a new promise-based API. For now the promise-based API just returns the
   raw HTTP request promise; this might change in the next version.
 */
var GitHub = require('github-api');

// unauthenticated client
var gh = new GitHub();
var gist = gh.getGist(); // not a gist yet
gist.create({
   public: true,
   description: 'My first gist',
   files: {
      "file1.txt": {
         contents: "Aren't gists great!"
      }
   }
}).then(function(httpResponse) {
   // Promises!
   var gist = httpResponse.data;
   gist.read(function(err, gist, xhr) {
      // if no error occurred then err == null

      // gist == httpResponse.data

      // xhr == httpResponse
   });
});

var GitHub = require('github-api');

// basic auth
var gh = new GitHub({
   username: 'FOO',
   password: 'NotFoo'
});

var me = gh.getUser();
me.getNotification(function(err, notifcations) {
   // do some stuff
});

var clayreimann = gh.getUser('clayreimann');
clayreimann.getStarredRepos()
   .then(function(httpPromise) {
      var repos = httpPromise.data;
   });

var GitHub = require('github-api');

// token auth
var gh = new GitHub({
   token: 'MY_OAUTH_TOKEN'
});

var yahoo = gh.getOrganization('yahoo');
yahoo.getRepos(function(err, repos) {
   // look at all the repos!
})

Changelog

1.0.0 - 2016/04/27

Complete rewrite in ES2015.

• Promise-ified the API
• Auto-generation of documentation
• Modularized codebase
• Refactored tests to run primarily in mocha

Breaking changes

Most of the breaking changes are just methods that got renamed. The changes to User and Organization are deeper changes that now scope a particular User or Organization to the entity they were instantiated with. You will need separate Users to query data about different user accounts.

• Github.getOrg → Github.getOrganization and requires an organization name.
• Github.getUser now requires a username.
• Issue.comment → Issue.createIssueComment
• Issue.create → Issue.createIssue
• Issue.edit → Issue.editIssue
• Issue.get → Issue.getIssue
• Issue.list → Issue.listIssues
• Repository.branch → Repository.createBranch
• Repository.collaborators → Repository.getCollaborators
• Repository.compare → Repository.compareBranches
• Repository.contents → Repository.getContents and now takes an argument for the content type
• Repository.delete has been removed.
• Repository.editHook → Repository.updateHook
• Repository.editRelease → Repository.updateRelease
• Repository.getCommit no longer takes a branch as the first argument
• Repository.getPull → Repository.getPullRequest
• Repository.getRef now returns the refspec from GitHub's API.
• Repository.getSha now returns the same data as GitHub's API. If the reqeusted object is not a directory then the response will contain a property SHA, and if the reqeusted object is a directory then the contents of the directory are stated.
• Repository.getStatuses → Repository.listStatuses
• Repository.listPulls → Repository.listPullRequests
• Repository.postBlob → Repository.createBlob
• Repository.postTree → Repository.createTree
• Repository.read remove in favor of Repository.getContents
• Repository.remove → Repository.deleteFile
• Repository.show → Repository.getDetails
• Repository.write → Repository.writeFile
• Search.code → Search.forCode
• Search.issues → Search.forIssues
• Search.repositories → Search.forRepositories
• Search.users → Search.forUsers
• The Search API no longer takes a string, it now takes an object with properties q, sort, and order to make the parts of the query easier to grok and to better match GitHub's API.
• User.gists → User.getGists
• User.notifications → User.getNotifications
• User.orgRepos → Organization.getRepos
• User.orgs → User.getOrgs
• User.repos → User.getRepos
• User.show → User.getProfile and no longer takes filtering options
• User.userStarred → User.getStarredRepos