Octokat.js
Try it out in your browser! (REPL)
Octokat.js provides a minimal higher-level wrapper around GitHub's API. It is being developed in the context of an EPUB3 Textbook editor for GitHub and a simple serverless kanban board (demo).
This package can be used in nodejs
or in the browser as an AMD module or using browserify.
Table of Contents
Key Features
- Works in
nodejs
, an AMD module in the browser, and as a bower library - Handles text and binary files
- Exposes everything available via the GitHub API (repos, teams, events, hooks, emojis, etc.)
- Supports
ETag
caching - Paged results
- Node-style callbacks as well as optional Promises (to avoid those debates)
- 100% of the GitHub API
- Starring and Following repositories, users, and organizations
- Editing Team and Organization Membership
- User/Org/Repo events and notifications
- Listeners for rate limit changes
- Public Keys
- Hooks (commit, comment, etc.)
- Uses Angular, jQuery, or native promises if available
- Markdown generation
- Preview APIs (Deployments, Teams, Licenses, etc)
- Enterprise APIs
For the full list of supported methods see ./src/grammar.coffee, ./examples/, Travis tests, or the ./test directory.
Overview
This library closely mirrors the https://developer.github.com/v3 documentation.
For example:
// `GET /repos/:owner/:repo` in the docs becomes:octo // `POST /repos/:owner/:repo/issues/:number/comments` becomes:octocomments
The last method should be a verb method. The verb method makes the async call and should either have a callback as the last argument or it returns a Promise (see Promises or Callbacks).
The basic structure of the verb method is:
.foos.fetch({optionalStuff:...})
yields a list of items (possibly paginated).foos(id).fetch(...)
yields a single item (issue, repo, user).foos.create(...)
creates a newfoo
.foos(id).update(...)
updates an existingfoo
.foos(id).add()
adds an existing User/Repo (id
) to the list.foos(id).remove()
removes a member from a list or deletes the object and yields a boolean indicating success.foos.contains(id)
tests membership in a list (yields true/false).foos(id).read()
is similar to.fetch()
but yields the text contents without the wrapper JSON.foos(id).readBinary()
is similar to.read()
but yields binary data
Examples
Below are some examples for using the library. For a semi-autogenerated list of more examples see ./examples/.
Chaining
You construct the URL by chaining properties and methods together and an async call is made once a verb method is called (see below).
octo = repo = octorepos'philschatz''octokat.js'# Check if the current user is a collaborator on a repo repocollaboratorscontainsUSERthen # If not, then star the Repo unless isCollaborator repostaradd then # Done!
Or, update a specific comment:
octo = token: ...octorepos'philschatz''octokat.js'issues1comments123123updatebody: 'Hello'then # Done!
Promises or Callbacks
This library supports Node.js-style callbacks as well as Promises.
To use a callback, just specify it as the last argument to a method. To use a Promise, do not specify a callback and the return value will be a Promise.
Example (get information on a repo):
# Using callbacks octorepos'philschatz''octokat.js'fetch consoleerrorerr if err # Do fancy stuff... # Using Promises octorepos'philschatz''octokat.js'fetchthen # Do fancy stuff then null consoleerrorerr
Read/Write/Remove a File
To read the contents of a file:
var octo = ;var repo = octo;repo // Use `.read` to get the raw file.;
To read the contents of a binary file:
var octo = ;var repo = octo;repo // Decodes the Base64-encoded content;
To read the contents of a file and JSON metadata:
var octo = ;var repo = octo;repo;
To update a file you need the blob SHA of the previous commit:
var octo = token: 'API_TOKEN';var repo = octo;var config = message: 'Updating file' content: sha: '123456789abcdef' // the blob SHA // branch: 'gh-pages'; repo;
Creating a new file is the same as updating a file but the sha
field in the config is omitted.
To remove a file:
var octo = token: 'API_TOKEN';var repo = octo;var config = message: 'Removing file' sha: '123456789abcdef' // branch: 'gh-pages'; repo;
Usage
All asynchronous methods accept a Node.js-style callback and return a Common-JS Promise.
In a Browser
Create an Octokat instance.
var octo = username: "USER_NAME" password: "PASSWORD"; var { console; }; octozen;octo; // Fetch repo infooctome; // Star a repo
Or if you prefer OAuth:
var octo = token: "OAUTH_TOKEN";
In a browser using RequireJS
;
In Node.js
Install instructions:
npm install octokat --save
var Octokat = ;var octo = username: "YOU_USER" password: "YOUR_PASSWORD"; // You can omit `cb` and use Promises insteadvar { console; }; octozen;octo; // Fetch repo infooctome; // Star a repooctome; // Un-Star a repo
Using bower
This file can be included using the bower package manager:
bower install octokat --save
Setup
This is all you need to get up and running:
Promises (Optional)
octokat.js
has the following optional dependencies when used in a browser:
- A Promise API (supports jQuery, AngularJS, or a Promise polyfill)
If you are already using jQuery or AngularJS in your project just be sure to include them before Octokat and it will use their Promise API.
Otherwise, you can include a Promise polyfill like jakearchibald/es6-promise:
Advanced Uses
Hypermedia
GitHub provides URL patterns in its JSON responses. These are automatically converted into methods.
You can disable this by setting disableHypermedia: true
in the options when creating a new Octokat(...)
.
For example:
octorepos'philschatz''octokat.js'fetchthen # GitHub returns a JSON which contains something like compare_url: 'https://..../compare/{head}...{base} # This is converted to a method that accepts 2 arguments repocomparesha1sha2fetch then # Done!
Paged Results
If a .fetch()
returns paged results then nextPage()
, previousPage()
, firstPage()
and lastPage()
are added to the returned Object. For example:
octorepos'philschatz''octokat.js'commitsfetchthen someCommitsnextPage then consolelog'2nd page of results'moreCommits
Preview new APIs
Octokat will send the Preview Accept header by default for several Preview APIs.
If you want to change this behavior you can force an acceptHeader
when instantiating Octokat.
For example:
var octo = token: 'API_TOKEN' acceptHeader: 'application/vnd.github.cannonball-preview+json';
Enterprise APIs
To use the Enterprise APIs add the root URL when instantiating Octokat:
var octo = token: 'API_TOKEN' rootURL: 'https://example.com/api/v3';
Using EcmaScript 6 Generators
This requires Node.js 0.11 with the --harmony-generators
flag:
var Octokat = ;var octo = ; var zen = octozen;var info = octo; console;console;
Uploading Releases
Uploading release assets requires a slightly different syntax because it involves setting a custom contentType and providing a possibly binary payload.
To upload (tested using nodejs) you can do the following:
contents = fs; repo ;
Parsing JSON
If you are using webhooks, the JSON returned by GitHub can be parsed using
octo.parse(json)
to return a rich object with all the methods Octokat provides.
Using URLs Directly
Instead of using Octokat to construct URLs, you can construct them yourself and still use Octokat for sending authentication information, caching, pagination, and parsing Hypermedia.
// Specify the entire URLocto; // Or, just the pathocto;
Development
- Run
npm install
- Run
npm test
to run Mocha tests for Node.js and the browser - Run
grunt dist
to generate the files in the./dist
directory
The unit tests are named to illustrate examples of using the API.
See Travis tests or run npm test
to see them.
linkedin/sepia is used to generate recorded HTTP fixtures from GitHub and philschatz/sepia.js uses them in the browser. If you are adding tests be sure to include the updated fixtures in the Pull Request.