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.
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 :)
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.
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.
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
-
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
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.
- Use conditional requests for github api calls and thus reduce 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.
-
/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
-
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
- 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