Octo.js
Octo.js is a simple, flexible, functional JavaScript library for interacting with GitHub's v3 API. It runs in node.js apps and the browser. It supports Basic Auth, OAuth 2, pagination and more.
Requires superagent — A lightweight library for supporting Ajax in the browser and HTTP in node.js.
All examples are written in CoffeeScript, but Octo.js itself is written in JavaScript.
Quick Example
api = octoapiapiget'/events'on'success'pubevents = resbody
api.get
sets up a closure, so you'll need to invoke it before the request is sent.
events = apiget'/events'perpage50on 'end'consolelog apilimitconsolelog eventspage #1events
Using in the browser
Download both superagent and octo.js and include them in the <head>
of your document.
Using in node.js
Install using npm
.
npm install octo
Require octo in your node.js script
octo = require 'octo'
Paging
One goal of octo.js was to make paging very simple. Paging is built right into the library.
events = apiget'/events'on'success'# the current pageeventspage# requests the next pageeventsnext# requests the previous pageeventsprevevents
What if you want to start on a different page and limit the number of results per page?
# Start on page 5 only returning 10 results per page apiget'/events'page5perpage10
Events
Octo.js supports three events: "success"
, "error"
and "end"
. These callbacks are registered per pager. This makes it easy to use the same callbacks for each page you request.
success
- Response status was in the 200 rangeerror
- Response wasn't in the 200 rangeend
- Fired at the end of every request, regarldess of status.
events = apiget'/events' on'success' consolelogresbody on'error' consolelogresbody on'end' consolelogresbody
Basic Auth
api = octoapiusername'foo'password'bar'apiget'/user'on'success' consolelogresbody
OAuth2
If you've registered your script or app as an OAuth app, you can use your token to authenticate with the api.
api = octoapitoken'MY APP TOKEN'apiget'/user'on'success' consolelogresbody
This will work with any registered OAuth application, but will return unauthorized if you've not registered your application with GitHub.
Getting an OAuth 2 token from the API
GitHub APIv3 allows you to programmatically fetch a token for use in scripts that might not be websites. Grabbing an OAuth token requires a username and password. Once you have a token, you can use it without a need for your username and password.
api = octoapiusername'foo'password'bar'apipost'/authorizations'note: 'my script'scopes: 'public_repo' on'success' consolelogresbody
Checking Rate limits
The GitHub API has a rate limit that's returned with the headers of every request. You can easily access this info to see your limit and how many requests you have left
apiget'/users/caged/repos'on'success'-> # Your limit per hour consolelog apilimit # Amount you have remaining in that hour consolelog apiremaining