octokit

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 agent

go-octokit is hypermedia-driven by default. Under the hood, it uses go-sawyer, the Go version of Ruby Sawyer.

Hypermedia in go-octokit

Resources in go-octokit contain not only data but hypermedia links:

package main

import "github.com/octokit/go-octokit/octokit"

func main() {
    client := octokit.NewClient(nil)
    usersService, err := client.Users(&octokit.UserURL, octokit.M{"user": "jingweno"})
    if err != nil  {
      // Handle error
    }

    user, result := usersService.Get()
    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
}

The Full Hypermedia Experience™

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() {
  rootService, _ := client.Root(nil)
  root, _ := rootService.Get()

  usersService, _ := client.Users(root.UserURL, octokit.M{"users": "jingweno"})
  user, _ := usersService.Get()
}

Pagination

package main

import "github.com/octokit/go-octokit/octokit"

func main() {
    client := octokit.NewClient(nil)
    usersService, err := client.Users(&octokit.UserURL, nil)
    if err != nil  {
      // Handle error
    }

    users, result := usersService.GetAll()
    if result.HasError() {
      // Handle error
    }

    // Do something with users

    // Next page
    usersService, err := client.Users(result.NextPage, nil)
    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

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

go-octokit is released under the MIT license. See LICENSE.md.