lighthouse

README

Golang Lighthouse API

A Golang client library for interacting with the Lighthouse API.

See cmd/lh for a Lighthouse CLI client based on this library.

Installation

go get -u github.com/nwidger/lighthouse

Usage

import "github.com/nwidger/lighthouse"

// Create an *http.Client which will authenticate with your Lighthouse
// API token.
client := lighthouse.NewClient("your-api-token")

// Or create an *http.Client which will authenticate with your Lighthouse
// API token and automatically rate limit API requests.
client := lighthouse.NewClientWithRateLimit("your-api-token")

// Or create an *http.Client which will authenticate with your
// Lighthouse email/password.
client := lighthouse.NewClientBasicAuth("your-email", "your-password")

// Or create an *http.Client which will authenticate with your
// Lighthouse email/password and automatically rate limit API requests.
client := lighthouse.NewClientBasicAuthWithRateLimit("your-email", "your-password")

// Create a *lighthouse.Service with your Lighthouse account and client.
// 'https://your-account-name.lighthouseapp.com'.
s := lighthouse.NewService("your-account-name", client)

// Create a service for interacting with each resource type in your
// account.

// Some resources are project specific.
projectID := 123456

// http://help.lighthouseapp.com/kb/api/ticket-bins
binsService := bins.NewService(s, projectID)

// http://help.lighthouseapp.com/kb/api/changesets
changesetService := changesets.NewService(s, projectID)

// http://help.lighthouseapp.com/kb/api/messages
messagesService := messages.NewService(s, projectID)

// http://help.lighthouseapp.com/kb/api/milestones
milestonesService := milestones.NewService(s, projectID)

// http://help.lighthouseapp.com/kb/api/projects
projectsService := projects.NewService(s)

// http://help.lighthouseapp.com/kb/api/tickets
ticketsService := tickets.NewService(s, projectID)

// http://help.lighthouseapp.com/kb/api/users-and-membership
profilesService := profiles.NewService(s)
tokensService := tokens.NewService(s)
usersService := users.NewService(s)

// Call List(), Get(), New(), Create(), Update(), Delete(),
// etc. methods on service.

See GoDoc reference for more details on each service type.

Documentation

Overview

Package lighthouse provides access to the Lighthouse API. http://help.lighthouseapp.com/kb/api

Index

• Constants
• func BasePath(account string) string
• func CheckResponse(resp *http.Response, expected int) error
• func ID(idStr string) (int, error)
• func NewClient(token string) *http.Client
• func NewClientBasicAuth(email, password string) *http.Client
• func NewClientBasicAuthWithRateLimit(email, password string) *http.Client
• func NewClientWithRateLimit(token string) *http.Client
• type ErrUnexpectedResponse
  • func (eir *ErrUnexpectedResponse) Error() string
• type ErrUnprocessable
  • func (eu *ErrUnprocessable) Error() string
  • func (eu *ErrUnprocessable) MarshalJSON() ([]byte, error)
  • func (eu *ErrUnprocessable) UnmarshalJSON(data []byte) error
• type ErrUnprocessables
  • func (eus ErrUnprocessables) Error() string
• type Plan
• type Service
  • func NewService(account string, client *http.Client) *Service
  • func (s *Service) Plan() (*Plan, error)
  • func (s *Service) RoundTrip(method, path string, body io.Reader) (*http.Response, error)
• type Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Examples

• NewService

Constants

const (
	StatusUnprocessableEntity = 422

	// DefaultRateLimitInterval controls the default rate limit
	// interval
	DefaultRateLimitInterval = 600 * time.Millisecond

	// DefaultRateLimitBurstSize control the default rate Limit
	// burst size
	DefaultRateLimitBurstSize = 1

	DefaultRateLimitRetryAttempts = 3
	DefaultRateLimitMaxRetryAfter = 125 * time.Second
)

Functions

func BasePath

func BasePath(account string) string

func CheckResponse

func CheckResponse(resp *http.Response, expected int) error

func ID

func ID(idStr string) (int, error)

func NewClient

func NewClient(token string) *http.Client

func NewClientBasicAuth

func NewClientBasicAuth(email, password string) *http.Client

func NewClientBasicAuthWithRateLimit

func NewClientBasicAuthWithRateLimit(email, password string) *http.Client

func NewClientWithRateLimit

func NewClientWithRateLimit(token string) *http.Client

Types

type ErrUnexpectedResponse

type ErrUnexpectedResponse struct {
	// The expected StatusCode
	ExpectedCode int

	// Resp.Body will always be closed.
	Resp *http.Response

	// BodyContents will contain the contents of Resp.Body if
	// Unprocessables is nil.
	BodyContents []byte

	// Unprocessables will not be nil if Resp.StatusCode was 422
	// StatusUnprocessableEntity.
	Unprocessables ErrUnprocessables
}

func (*ErrUnexpectedResponse) Error

func (eir *ErrUnexpectedResponse) Error() string

type ErrUnprocessable

type ErrUnprocessable struct {
	Field   string
	Message string
}

func (*ErrUnprocessable) Error

func (eu *ErrUnprocessable) Error() string

func (*ErrUnprocessable) MarshalJSON

func (eu *ErrUnprocessable) MarshalJSON() ([]byte, error)

func (*ErrUnprocessable) UnmarshalJSON

func (eu *ErrUnprocessable) UnmarshalJSON(data []byte) error

type ErrUnprocessables

type ErrUnprocessables []*ErrUnprocessable

func (ErrUnprocessables) Error

func (eus ErrUnprocessables) Error() string

type Plan

type Plan struct {
	Plan     string `xml:"plan" json:"plan"`
	Free     bool   `xml:"free" json:"free"`
	Users    int    `xml:"users" json:"users"`
	Projects int    `xml:"projects" json:"projects"`
	Storage  int    `xml:"storage" json:"storage"`
}

type Service

type Service struct {
	BasePath string
	Client   *http.Client

	// RateLimitRetryRequests controls whether *Service.RoundTrip
	// will automatically retry rate-limited requests that receive
	// a 429 Too Many Requests response.
	RateLimitRetryRequests bool
	// RateLimitRetryAttempts controls how many attempts
	// *Service.RoundTrip will make for a rate-limited request
	// before giving up.  If RateLimitRetryRequests is set and
	// RateLimitRetryAttempts is zero, the value of
	// DefaultRateLimitRetryAttempts is used.
	// RateLimitRetryAttempts is ignored if RateLimitRetryRequests
	// is not set.
	RateLimitRetryAttempts int
	// RateLimitMaxRetryAfter controls the maximum time
	// *Service.RoundTrip will wait between each retry attempt.
	// *Service.RoundTrip uses the number of seconds returned in
	// the X-Rate-Limit-Retry-After header of the 429 Too Many
	// Requests response as the amount of time to wait between
	// each attempt, using RateLimitMaxRetryAfter as an upper
	// bound on this value.  If RateLimitRetryRequests is set and
	// RateLimitMaxRetryAfter is zero, the value of
	// DefaultRateLimitMaxRetryAfter is used.
	// RateLimitMaxRetryAfter is ignored if RateLimitRetryRequests
	// is not set.
	RateLimitMaxRetryAfter time.Duration
}

func NewService

func NewService(account string, client *http.Client) *Service

Example

package main

import (
	"fmt"
	"log"

	"github.com/nwidger/lighthouse"
	"github.com/nwidger/lighthouse/tickets"
)

func main() {
	// Create an *http.Client which will authenticate with your Lighthouse
	// API token.
	client := lighthouse.NewClient("your-api-token")

	// Create a *lighthouse.Service with your Lighthouse account and client.
	// 'https://your-account-name.lighthouseapp.com'.
	s := lighthouse.NewService("your-account-name", client)

	// Create a *tickets.Service instance for interacting with
	// project 123456's tickets.
	// http://help.lighthouseapp.com/kb/api/tickets
	ticketsService := tickets.NewService(s, 123456)

	// Search the project's tickets.
	// http://help.lighthouseapp.com/kb/getting-started/how-do-i-search-for-tickets
	ts, err := ticketsService.List(&tickets.ListOptions{
		Query: `responsible:me milestone:v1.2 tagged:bug sort:updated`,
		Limit: tickets.MaxLimit,
		Page:  1,
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, t := range ts {
		fmt.Println(t.Number, t.Title, t.Tags, t.Priority, t.State)
	}
}

func (*Service) Plan

func (s *Service) Plan() (*Plan, error)

Get account plan details. Undocumented, see http://help.lighthouseapp.com/discussions/api-developers/1100-check-if-using-free-plan.

func (*Service) RoundTrip

func (s *Service) RoundTrip(method, path string, body io.Reader) (*http.Response, error)

type Transport

type Transport struct {
	// API token to use for authentication.  If set this is used
	// instead of Email/Password.
	Token string
	// If Token is set and TokenAsBasicAuth is true, send API
	// token in Authorization header using Basic Authentication
	// with the API token as the username and 'x' as the password.
	TokenAsBasicAuth bool
	// If Token is set, TokenAsBasicAuth is false and
	// TokenAsParameter is true, send API token in '_token' URL
	// parameter.
	TokenAsParameter bool

	// Email and password to use for authentication.
	Email, Password string

	// Base specifies the mechanism by which individual HTTP
	// requests are made.  If Base is nil, http.DefaultTransport
	// is used.
	Base http.RoundTripper

	// RateLimitInterval controls the rate limit interval using a
	// token bucket.  If not set no rate limiting will occur.  See
	// https://en.wikipedia.org/wiki/Token_bucket for more about
	// token buckets.
	RateLimitInterval time.Duration
	// RateLimitBurstSize controls the rate limit burst size.  If
	// RateLimitInterval is not set, RateLimitBurstSize is
	// ignored.
	RateLimitBurstSize int
	// contains filtered or unexported fields
}

Transport wraps another http.RoundTripper and ensures the outgoing request is properly authenticated

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)