go-octokit 
Go toolkit for the GitHub API.
Status
Very experimental. APIs are subject to change.
Motivation
go-octokit is designed to be a hypermedia API client that wraps the GitHub API.
Hypermedia Client
HAL is a simple format that gives a consistent and easy way to hyperlink between resources in web API.
Being a client for HAL means it can navigate around the resources by following hyperlinks.
go-octokit is a hypermedia client for the GitHub API that it can traverse links by following the GitHub API conventions.
Under the hood, it uses go-sawyer, the Go version of the Ruby Sawyer.
Resource Objects
Resources in go-octokit contain not only data but hyperlinks:
package main
import "github.com/octokit/go-octokit/octokit"
func main() {
client := octokit.NewClient(nil)
url, err := octokit.UserURL.Expand(octokit.M{"user": "jingweno"})
if err != nil {
// Handle error
}
user, result := client.Users(url).One()
if result.HasError() {
// Handle error
}
fmt.Println(user.ReposURL) // https://api.github.com/users/jingweno/repos
}
URI templates
Many hypermedia links have variable placeholders. go-octokit supports URI Templates for parameterized URI expansion:
package main
import "github.com/octokit/go-octokit/octokit"
func main() {
url, _ := octokit.UserURL.Expand(octokit.M{"user": "jingweno"})
fmt.Println(url) // https://api.github.com/users/jingweno
}
API Discoverability
If you want to use go-octokit as a pure hypermedia API client, you can
start at the API root and follow hypermedia links which drive the application state transitions:
package main
import "github.com/octokit/go-octokit/octokit"
func main() {
rootURL, _ := client.RootURL.Expand(nil)
root, _ := client.Root(rootURL).One()
userURL, _ := root.UserURL.Expand(octokit.M{"users": "jingweno"})
user, _ := client.Users(userURL).One()
}
Pagination
package main
import "github.com/octokit/go-octokit/octokit"
func main() {
url, err := octokit.UserURL.Expand(nil)
if err != nil {
// Handle error
}
users, result := client.Users(url).All()
if result.HasError() {
// Handle error
}
// Do something with users
// Next page
nextPageURL, _ := result.NextPage.Expand(nil)
users, result := client.Users(nextPageURL).All()
if result.HasError() {
// Handle error
}
// Do something with users
}
Caching
Client-side caching is the #1 thing to do to make a hypermedia client more performant.
We plan to support this in the near future.
More examples are available.
Release Notes
See Releases.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
License
go-octokit is released under the MIT license. See
LICENSE.