philschatz/octokit.js — pull request #41 by philschatz (2014-05-10 19:45:08+00:00)
Title: WIP Redesign to align with GitHub's conventions

This code change leverages the URL patterns GitHub provides and converts the returned JSON into objects which allows nifty daisy-chaining.

Example:

```
octo = new Octokit()
octo.repo('philschatz', 'octokit.js')
.then (repo) ->
# Find the collaborators
repo.collaborators()
.then (collaborators) ->
# Get the gists for the first collaborator
collaborators[0].gists()
.then (gists) ->
# Check if the first gist is starred
gists[0].starred()
.then (isStarred) ->
# Star it if it has not been starred
unless starred
gists[0].starred.add()
.then () ->
# Done!
```

As a result, there are many methods automatically generated.

The basic structure of these methods is:

- `.foo()` returns a list
- `.foo(id)` tests membership in a list (returns true/false) or returns a single item (ie key)
- `.foo.create()` creates a new `foo`
- `.foo.add()` adds an existing User/Repo to the list
- `.foo.remove()` removes a member from a list or deletes the object

# Repo Methods:

- `repo.html()`
- `repo.fork()`
- `repo.keys()`
- `repo.keys(id)`
- `repo.collaborators()` : Return a list of users
- `repo.collaborators(user)` : Checks if `user` is a collaborator
- `repo.collaborators.add(user)`
- `repo.collaborators.remove(user)`
- `repo.teams()`
- `repo.hooks()`
- `repo.hooks(id)`
- `repo.hooks.create(options)`
- `repo.hooks.remove(id)`
- `repo.hooks.test(id)`
- `repo.hooks.update(id, options)`
- `repo.issueEvents()`
- `repo.issueEvents(id)`
- `repo.events()`
- `repo.assignees()`
- `repo.assignees(id)` : Check if user is assigned
- `repo.branches()` : get list of branches
- `repo.branch(id)` : get single branch
- `repo.tags()` : list of tags
- `repo.blobs()` : list of blobs
- `repo.blobs(sha)` : retreive single blob
- `repo.gitTags()` : list of tags
- `repo.gitTags(sha)` : specific tag
- `repo.gitRefs()`
- `repo.gitRefs(sha)`
- `repo.trees()`
- `repo.trees(sha)`
- `repo.statuses(sha)`
- `repo.languages()` : list of languages
- `repo.stargazers()`
- `repo.contributors()`
- `repo.subscribers()`
- `repo.subscription()`
- `repo.commits()`
- `repo.commits(sha)`: return a single commit
- `repo.gitCommits()`
- `repo.gitCommits(sha)`
- `repo.comments()`
- `repo.comments(number)`
- `repo.issueComment(number)`
- `repo.contents(path, ...TODO)`
- `repo.compare(base, head)`
- `repo.merges()`
- `repo.archive()`
- `repo.archive(format)`
- `repo.archive(format, ref)`
- `repo.downloads()`
- `repo.issues.events()` # TODO: SHould I be smart about issueEvents and issue.events ?
- `repo.pulls()`
- `repo.pulls(number)`
- `repo.milestones()`
- `repo.milestones(number)`
- `repo.notifications()`
- `repo.labels()`
- `repo.labels(name)`
- `repo.releases(...TODO)`

- `repo.git.commits()`
- `repo.git.commits.create(options)`
- `repo.git.refs()`
- `repo.git.refs(sha)`
- `repo.git.refs.create(config)`
- `repo.git.refs.remove(sha)`

- `repo.git.heads()`
- `repo.git.heads.update(id, config)`

- `repo.git.blobs(id, isBase64)`
- `repo.git.blobs.create(content, isBase64)`

- `repo.git.trees(id)`
- `repo.git.trees.create(config)`

- `repo.fetch()`
- `repo.update(options)`
- `repo.remove()`

- `repo.pullRequests.create(options)`
- `repo.network.events()`
- `repo.hook(id)` # TODO: Maybe this is not needed

TODO: ssh_url, clone_url, and svn_url should not become functions

- `repo.mirror (NONE????)`

# User

- `user.html()`
- `user.followers()`
- user.following... #TODO: Make this a getall/getone/add/remove function+
- `user.gists()`
- user.starred...
- user.subscriptions...
- user.organizations...
- `user.repos()`
- `user.events()`
- `user.receivedEvents()`
- `user.fetch()`
- `user.orgs()`
- `user.keys()`
- `user.keys(id)`
- `user.keys.add()`
- `user.keys.remove(id)`

- `user.avatar()`
- `user.starred()` : List what this user has starred
- `user.starred(owner)`
- `user.starred(owner, repo)`
- `user.subscriptions()`
- `user.organizations()`

# Gist

- `gist.forks()`
- `gist.commits()`
- `gist.html()`
- `gist.comments()`
- `gist.fetch()`
- `gist.update()`
- `gist.remove()`
- `gist.fork()`
- `gist.starred()`
- `gist.starred.add()`
- `gist.starred.remove()`

# Team

- `team.update(config)`
- `team.remove()`
- `team.members()` : Get list of members
- `team.members(user)` : Check is user is a member
- `team.members.add(user)`
- `team.members.remove(user)`
- `team.repositories()`
- `team.repositories.add(user, name)`
- `team.repositories.remove(user, name)`