githubapi.js

githubApi.js

githubapi.js allow to access github api in javascript. It can be used from node.js or browser. The library code is available at /build/githubAPI.js There is a fully documented API also available at the end of this README.md.

Install it

To install for node.js, just do

npm install githubapi.js

To install for browser, just do

bower install githubapi.js

or just include build/githubAPI.js in your projects the way you see fit :)

Show, Don't Tell

Let's see how to use githubapi.js. There are examples for you to look at and see how to use it. The examples shows usage from the browser and from node.js. You can find them in /examples/express/public.

• using github authentication It shows how to login/logout with the github authentication. A logged in user will give profile information and access_token. The access_token is given to github to authenticate the user. It can be used from the browser or from node.js.
• use github api thru a rest There is example express routes called githubapi-rest-examples. it provides a example of REST API on top of githubapi.js. This is a good place to see how to use githubapi.js from node.js.
• upload from browser It upload files from the browser directly to gihub. It is possible to upload from node.ns too, but uploading from the user's browser, save bandwidth on servers. It is a good place to see how to use githubapi.js from browser.
• index.html It is just the examples homepage. once you launch the server, goto http://127.0.0.1:8000/ to see it.
• app.js is the usual application for express server. It is a good place to see how to initialize the github authentication in your own server.

Now, let's run the server. A server is required because github api requires authentications for many calls. An authentication server is provided as examples in /examples/express, coded with express as you may have guessed. It run the authentication server and serve /examples/express/public as static.

First you need to authenticate yourself on github. It will give permissions to example application.

Getting application's keys from github

You need to create register your application on github. At the moment, it is in user -> setting -> applications -> register new application. link

Get the clientID and clientSecret you see on top.

Then setup those value into your examples server. First, copy examples/expess/app_github_keys.sample.js into examples/expess/app_github_keys.js Then replace the values by your own clientID/clientSecret. And you are done.

How to run the example

Once you got the keys setup, launch the server this way and go to http://127.0.0.1:8000/ with your browser

cd examples/express
make server

Makefile

• make build - build the library
• make minify - build the library and minify it
• make server - launch dev server
• make jsdoc - generate docs/api.md from jsdoc in /src

Motivation

This library is working well in my experience, They are other wrapper for github api, i dont claim mine is better :) The other libraries seemed good when i looked. be sure to check them out.

I had to implement my own github api wrapper. It was a core part of a project. So i had to really understand it, i could not rely on a 3rd party library. This is why i reimplemented it.

TODO - Possible Improvements

• Use conditional requests for github api calls and thus reduce rate limits
  • see doc on conditional requests
  • see doc on rate limits
• githubapi.js doesn't implement all github api v3 calls, far from it.
  • But it does implement the call i need now.
  • Maybe implement the whole API later.

Folders

• /build - the built source, the one you need as a user of the library
• /src - the source of the library itself, where you go to develop this api
• /examples - the examples you can run to learn how to use this library
  • /examples/express - the express server needed to run the examples

API

Here is the api documentation. It is complete and automatically generated from jsdoc to be sure to stay in sync. It has been pasted from the original.

#class: Github Members

• class: Github
  • new Github(accessToken, profile)
  • Github.userBlackList
  • Github.Flow()
  • github.getRepos(onLoad)
  • github.createRepo()
  • github.deleteRepo()
  • github.createOrUpdateFile()
  • github.filesList(repoName, rootPath, onLoad)
  • github.get(path, onLoad)
  • github.post(path, onLoad)
  • github.put(path, onLoad)
  • github.delete(path, onLoad)
  • github._requestRead(method, path, onLoad)
  • github._requestWrite(method, path, dataToPost, onLoad)
  • github.getContent(repoName, path, onLoad)
  • github.getContent(repoName, path, onLoad)
  • github.getReadme(repoName, onLoad)
  • github.createFile(repoName, path, message, content, onLoad)
  • github.updateFile()
  • github.deleteFile()
  • github.createFork()
  • github.checkUserBlacklist(userName)

##new Github(accessToken, profile) Build the tool itself

Params

• accessToken String - the access token you got from authentication
• profile Object - the profile of your user from github

##Github.userBlackList user blacklist

Type: Array.<String>
##Github.Flow() Build a flow to handle asynchronous data flow gowiththeflow.js - https://github.com/jeromeetienne/gowiththeflow.js

##github.getRepos(onLoad) get all repositories

Params

• onLoad function - callback called on load

##github.createRepo() https://developer.github.com/v3/repos/#create

##github.deleteRepo() https://developer.github.com/v3/repos/#delete-a-repository

• require scope 'delete_repo'

##github.createOrUpdateFile() https://developer.github.com/v3/repos/contents/#update-a-file

##github.filesList(repoName, rootPath, onLoad) get a list of all the file at rootPath

Params

• repoName String - the name of the repository
• rootPath String - the root path where to start, likely '' for the whole thing
• onLoad function - callback called once data are loaded

##github.get(path, onLoad) get data

Params

• path String - the api path
• onLoad function - callback called when the result is loaded

##github.post(path, onLoad) post data

Params

• path String - the api path
• onLoad function - callback called when the result is loaded

##github.put(path, onLoad) put data

Params

• path String - the api path
• onLoad function - callback called when the result is loaded

##github.delete(path, onLoad) delete data

Params

• path String - the api path
• onLoad function - callback called when the result is loaded

##github._requestRead(method, path, onLoad) Perform a READ on github API

Params

• method String - "POST" "PUT" "DELETE" this kindof thing
• path String - the api path
• onLoad function - callback called when the result is loaded

##github._requestWrite(method, path, dataToPost, onLoad) Perform a WRITE on github API

Params

• method String - "POST" "PUT" "DELETE" this kindof thing
• path String - the api path
• dataToPost Object | String - the data to send along
• onLoad function - callback notified when the result is loaded

##github.getContent(repoName, path, onLoad) get contents - https://developer.github.com/v3/repos/contents/#get-contents

Params

• repoName String - the repository name
• path String - the path to the content
• onLoad function - callback called on load

##github.getContent(repoName, path, onLoad) get contents - https://developer.github.com/v3/repos/contents/#get-contents

Params

• repoName String - the repository name
• path String - the path to the content
• onLoad function - callback called on load

##github.getReadme(repoName, onLoad) get README - https://developer.github.com/v3/repos/contents/#get-the-readme

Params

• repoName String - the repository name
• onLoad function - callback called on load

##github.createFile(repoName, path, message, content, onLoad) https://developer.github.com/v3/repos/contents/#create-a-file

Params

• repoName type - [description]
• path type - [description]
• message type - [description]
• content type - [description]
• onLoad type - [description]

Returns: type - [description]
##github.updateFile() https://developer.github.com/v3/repos/contents/#update-a-file

##github.deleteFile() https://developer.github.com/v3/repos/contents/#delete-a-file

##github.createFork() https://developer.github.com/v3/repos/forks/#create-a-fork

##github.checkUserBlacklist(userName) test if the username is in the user blacklist

Params

• userName String - the username