octonode
octonode is a library for nodejs to access the github v3 api
Installation
npm install octonode
Usage
var github = ; // Then we instantiate a client with or without a token (as show in a later section) var ghme = client;var ghuser = client;var ghrepo = client;var ghorg = client;var ghissue = client;var ghmilestone = client;var ghlabel = clientlabel'pksunkara/hub' 'todo';var ghpr = client;var ghgist = client;var ghteam = client; var ghsearch = client;
Build a client which accesses any public information
var client = github; client;
Build a client from an access token
var client = github; client;
Build a client from credentials
var client = github; client;
Build a client from client keys
var client = github; client;
Request Options
Request options can be set by setting defaults on the client. (e.g. Proxies)
var client = github; clientrequestDefaults'proxy' = 'https://myproxy.com:1085'
These options are passed though to request
, see their API here: https://github.com/mikeal/request#requestoptions-callback
Proxies
You can set proxies dynamically by using the example above, but Octonode will respect environment proxies by default. Just set this using:
export HTTP_PROXY='https://myproxy.com:1085'
if you are using the command line
Many of the below use cases use parts of the above code
Authentication
Authenticate to github in cli mode (desktop application)
githubauth;
Revoke authentication to github in cli mode (desktop application)
githubauth;
Authenticate to github in web mode (web application)
// Web application which authenticates to githubvar http = url = qs = github = ; // Build the authorization config and urlvar auth_url = githubauth; // Store info to verify against CSRFvar state = auth_url; // Web serverhttp; console;
Rate Limiting
You can also check your rate limit status by calling the following.
client;
API Callback Structure
All the callbacks for the following will take first an error argument, then a data argument, like this:
ghme;
Pagination
If a function is said to be supporting pagination, then that function can be used in many ways as shown below. Results from the function are arranged in pages.
The page argument is optional and is used to specify which page of issues to retrieve. The perPage argument is also optional and is used to specify how many issues per page.
// Normal usage of functionghrepo; //array of first 30 issues // Using pagination parametersghrepo; //array of second 100 issuesghrepo; //array of 30 issues from page 10 // Pagination parameters can be set with query object tooghrepo; //array of second 100 issues which are closed
Github authenticated user api
Token/Credentials required for the following:
Get information about the user (GET /user)
ghme; //json
Update user profile (PATCH /user)
ghme;
Get emails of the user (GET /user/emails)
ghme; //array of emails
Set emails of the user (POST /user/emails)
ghme; //array of emailsghme; //array of emails
Delete emails of the user (DELETE /user/emails)
ghme;ghme;
Get the followers of the user (GET /user/followers)
ghme; //array of github users
Get users whom the user is following (GET /user/following)
This query supports pagination.
ghme; //array of github users
Check if the user is following a user (GET /user/following/marak)
ghme; //boolean
Follow a user (PUT /user/following/marak)
ghme;
Unfollow a user (DELETE /user/following/marak)
ghme;
Get public keys of a user (GET /user/keys)
ghme; //array of keys
Get a single public key (GET /user/keys/1)
ghme; //key
Create a public key (POST /user/keys)
ghme; //key
Update a public key (PATCH /user/keys/1)
ghme; //key
Delete a public key (DELETE /user/keys/1)
ghme;
Get the starred repos for the user (GET /user/starred)
This query supports pagination.
ghme; //array of repos
Check if you have starred a repository (GET /user/starred/pksunkara/octonode)
ghme; //boolean
Star a repository (PUT /user/starred/pksunkara/octonode)
ghme;
Unstar a repository (DELETE /user/starred/pksunkara/octonode)
ghme;
Get the subscriptions of the user (GET /user/subscriptions)
This query supports pagination.
ghme; //array of repos
List your public and private organizations (GET /user/orgs)
This query supports pagination.
ghme; //array of orgs
List your repositories (GET /user/repos)
This query supports pagination.
ghme; //array of repos
Create a repository (POST /user/repos)
ghme; //repo
Fork a repository (POST /repos/pksunkara/hub/forks)
ghme; //forked repo
Github users api
No token required for the following
Get information about a user (GET /users/pksunkara)
ghuser; //json
Get user followers (GET /users/pksunkara/followers)
This query supports pagination.
ghuser; //array of github users
Get user followings (GET /users/pksunkara/following)
This query supports pagination.
ghuser; //array of github users
Get events performed by a user (GET /users/pksunkara/events)
This query supports pagination.
Optionally, supply an array of Event Types to filter by.
ghuser; //array of PushEvent events
Or leave it out to get all Event Types.
ghuser; //array of events
Get user public organizations (GET /users/pksunkara/orgs)
This query supports pagination.
ghuser; //array of organizations
Github repositories api
Get information about a repository (GET /repos/pksunkara/hub)
ghrepo; //json
Get the collaborators for a repository (GET /repos/pksunkara/hub/collaborators)
ghrepo; //array of github users
Check if a user is collaborator for a repository (GET /repos/pksunkara/hub/collaborators/marak)
ghrepo; //boolean
Get the commits for a repository (GET /repos/pksunkara/hub/commits)
ghrepo; //array of commits
Get a certain commit for a repository (GET /repos/pksunkara/hub/commits/18293abcd72)
ghrepo; //commit
Get the tags for a repository (GET /repos/pksunkara/hub/tags)
ghrepotagscallback; //array of tags
Get the releases for a repository (GET /repos/pksunkara/hub/releases)
ghrepo; //array of releases
Get the languages for a repository (GET /repos/pksunkara/hub/languages)
ghrepo; //array of languages
Get the contributors for a repository (GET /repos/pksunkara/hub/contributors)
ghrepo; //array of github users
Get the branches for a repository (GET /repos/pksunkara/hub/branches)
This query supports pagination.
ghrepo; //array of branches
Get a branch for a repository (GET /repos/pksunkara/hub/branches/master)
ghrepo; //branch
Get the issues for a repository (GET /repos/pksunkara/hub/issues)
This query supports pagination.
ghrepo; //array of issues
Create an issue for a repository (POST /repos/pksunkara/hub/issues)
ghrepo; //issue
Get the milestones for a repository (GET /repos/pksunkara/hub/milestones)
This query supports pagination.
ghrepo; //array of milestones
Create a milestone for a repository (POST /repos/pksunkara/hub/milestones)
ghrepo; //milestone
Get the labels for a repository (GET /repos/pksunkara/hub/labels)
This query supports pagination.
ghrepo; //array of labels
Create a label for a repository (POST /repos/pksunkara/hub/labels)
ghrepolabel "name": "Priority" "color": "ff0000" callback; //label
Get the pull requests for a repository (GET /repos/pksunkara/hub/pulls)
This query supports pagination.
ghrepo; //array of pull requests
Create a pull request (POST /repos/pksunkara/hub/pulls)
ghrepo; //pull request
Get the hooks for a repository (GET /repos/pksunkara/hub/hooks)
This query supports pagination.
ghrepo; //array of hooks
Create a hook (POST /repos/pksunkara/hub/hooks)
ghrepo; // hook
Get the README for a repository (GET /repos/pksunkara/hub/readme)
ghrepo; //fileghrepo; //file
Get the root contents on a branch called "myBranch"
ghrepo;
Get the contents of a path in repository
ghrepo; //pathghrepo; //path
Create a file at a path in repository
ghrepo; //pathghrepo; //path
Update a file at a path in repository
ghrepo; //pathghrepo; //path
Delete a file at a path in repository
ghrepo; //pathghrepo; //path
Get archive link for a repository
ghrepoarchive'tarball' callback; //link to archiveghrepoarchive'zipball' 'v0.1.0' callback; //link to archive
Get the blob for a repository (GET /repos/pksunkara/hub/git/blobs/SHA)
ghrepo; //blob
Get users who starred a repository (GET /repos/pksunkara/hub/stargazers)
ghrepo; //array of usersghrepo; //array of usersghrepo; //array of users
Get the teams for a repository (GET /repos/pksunkara/hub/teams)
ghrepo; //array of teams
Get a git tree (GET /repos/pksunkara/hub/git/trees/18293abcd72)
ghrepo; //treeghrepo; //recursive tree
Delete the repository (DELETE /repos/pksunkara/hub)
ghrepo;
List statuses for a specific ref (GET /repos/pksunkara/hub/statuses/master)
ghrepo; //array of statuses
Create status (POST /repos/pksunkara/hub/statuses/SHA)
ghrepostatus'18e129c213848c7f239b93fe5c67971a64f183ff' "state": "success" "target_url": "http://ci.mycompany.com/job/hub/3" "description": "Build success." callback; // created status
Github organizations api
Get information about an organization (GET /orgs/flatiron)
ghorg; //json
Update an organization (POST /orgs/flatiron)
ghorg; // org
List organization repositories (GET /orgs/flatiron/repos)
This query supports pagination.
ghorg; //array of repos
Create an organization repository (POST /orgs/flatiron/repos)
ghorg; //repo
Get an organization's teams (GET /orgs/flatiron/teams)
ghorg; //array of teams
Get an organization's members (GET /orgs/flatiron/members)
This query supports pagination.
ghorg; //array of github users
Check an organization member (GET /orgs/flatiron/members/pksunkara)
ghorg; //boolean
Create an organization team (POST /orgs/flatiron/teams)
ghorg;
Github issues api
Get a single issue (GET /repos/pksunkara/hub/issues/37)
ghissue; //issue
Edit an issue for a repository (PATCH /repos/pksunkara/hub/issues/37)
ghissue; //issue
List comments on an issue (GET /repos/pksunkara/hub/issues/37/comments)
This query supports pagination.
ghissue; //array of comments
Github milestones api
Get a single milestone (GET /repos/pksunkara/hub/milestones/37)
ghmilestone; //milestone
Edit a milestone for a repository (PATCH /repos/pksunkara/hub/milestones/37)
ghmilestone; //milestone
Delete a milestone for a repository (DELETE /repos/pksunkara/hub/milestones/37)
ghmilestone; //milestone
Github labels api
Get a single label (GET /repos/pksunkara/hub/labels/todo)
ghlabel; //label
Edit a label for a repository (PATCH /repos/pksunkara/hub/labels/todo)
ghlabel; //label
Delete a label for a repository (PATCH /repos/pksunkara/hub/labels/todo)
ghlabel; //label
Github pull requests api
Get a single pull request (GET /repos/pksunkara/hub/pulls/37)
ghpr; //pull request
Update a pull request (PATCH /repos/pksunkara/hub/pulls/37)
ghpr; //pull request
Close a pull request
ghpr; //pull request
Get if a pull request has been merged (GET /repos/pksunkara/hub/pulls/37/merge)
ghpr; //boolean
List commits on a pull request (GET /repos/pksunkara/hub/pulls/37/commits)
ghpr; //array of commits
List comments on a pull request (GET /repos/pksunkara/hub/pulls/37/comments)
ghpr; //array of comments
List files in pull request (GET /repos/pksunkara/hub/pulls/37/files)
ghpr; //array of files
Github gists api
List authenticated user's gists (GET /gists)
This query supports pagination.
ghgist; //array of gists
List authenticated user's public gists (GET /gists/public)
This query supports pagination.
ghgist; //array of gists
List authenticated user's starred gists (GET /gists/starred)
This query supports pagination.
ghgist; //array of gists
List a user's public gists (GET /users/pksunkara/gists)
This query supports pagination.
ghgist; //array of gists
Get a single gist (GET /gists/37)
ghgist; //gist
Create a gist (POST /gists)
ghgist callback); //gist
Edit a gist (PATCH /gists/37)
ghgist; //gist
Delete a gist (DELETE /gists/37)
ghgist;
Fork a gist (POST /gists/37/forks)
ghgist; //gist
Star a gist (PUT /gists/37/star)
ghgist;
Unstar a gist (DELETE /gists/37/unstar)
ghgist;
Check if a gist is starred (GET /gists/37/star)
ghgist; //boolean
List comments on a gist (GET /gists/37/comments)
ghgist; //array of comments
Create a comment (POST /gists/37/comments)
ghgist; //comment
Get a single comment (GET /gists/comments/1)
ghgist; //comment
Edit a comment (POST /gists/comments/1)
ghgist; //comment
Delete a comment (DELETE /gists/comments/1)
ghgist;
Github teams api
Get a team (GET /team/37)
ghteam; //json
Get the team members (GET /team/37/members)
ghteam; //array of github users
Check if a user is part of the team (GET /team/37/members/pksunkara)
ghteam; //boolean
Add a user to a team (PUT /team/37/members/pksunkara)
ghteam; //boolean
Remove a user from a team (DELETE /team/37/members/pksunkara)
ghteam; //boolean
List all repos of a team (GET /team/37/repos)
ghteam; //array of repos
Github search api
Search issues
ghsearch; //array of search results
Search repositories
ghsearch; //array of search results
Search users
ghsearch; //array of search results
Search code
ghsearchcode q: 'auth+in:file+repo:pksunkara/hub' sort: 'created' order: 'asc' callback; //array of search results
Testing
npm test
If you like this project, please watch this and follow me.
Contributors
Here is a list of Contributors
TODO
The following method names use underscore as an example. The library contains camel cased method names.
// public repos for unauthenticated, private and public for authenticatedme;me;me;me;me; // organization datavar org = octonode; org;org;org;org;org; org;org;org;org;org;org;org;org;org;org;org;org;org; var repo = octonode; repo; // collaborator informationrepo;repo; // commit datarepo;repo;repo;repo;repo;repo;repo; // downloadsrepo;repo;repo;repo; // keysrepo;repo;repo;repo;repo; // watcher datarepo; // pull requestsrepo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo;repo; // raw git accessrepo;repo;repo;repo;repo;repo;repo;
I accept pull requests and guarantee a reply back within a day
License
MIT/X11
Bug Reports
Report here. Guaranteed reply within a day.
Contact
Pavan Kumar Sunkara (pavan.sss1991@gmail.com)