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.md.

pcasaretto/go-octokit