A Go package for connecting to Phabricator via the Conduit API.
Switch branches/tags
Clone or download
#13 Compare This branch is 51 commits ahead of jpoehls:master.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
constants Added remarkup.process method Oct 16, 2016
core style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
entities support maniphest.gettasktransactions Oct 27, 2016
requests support maniphest.gettasktransactions Oct 27, 2016
resources/harbormaster fix(harbormaster): Clean up directory before running tests Sep 12, 2016
responses support maniphest.gettasktransactions Oct 27, 2016
test/server feat(conduit): Add support for conduit.query Sep 12, 2016
util Add tests for utilities Oct 25, 2015
.gitignore chore(glide): Update glide.lock Sep 12, 2016
LICENSE Add LICENSE Oct 25, 2015
README.md support maniphest.gettasktransactions Oct 27, 2016
client.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
conduit.go fix(conduit.query): Include metadata with requests Oct 16, 2016
conduit_test.go feat(conduit): Add support for conduit.query Sep 12, 2016
dialer.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
dialer_test.go feat(conduit): Add support for conduit.query Sep 12, 2016
differential.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
diffusion.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
file.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
glide.lock chore(glide): Update glide.lock Sep 12, 2016
glide.yaml chore(glide): Update glide.lock Sep 12, 2016
macro.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
maniphest.go support maniphest.gettasktransactions Oct 27, 2016
paste.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
phid.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
phriction.go Added API method support Oct 17, 2016
projects.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
remarkup.go Added API method support Oct 17, 2016
repository.go style(gonduit): Keep a few lines under 80 characters Sep 12, 2016
user.go feat(user): Add user.query method Oct 16, 2016

README.md

gonduit GoDoc

A Go client for interacting with Phabricator via the Conduit API.

Getting started

Installing the library

A simple go get should do it:

go get github.com/etcinit/gonduit

For reproducible builds, you can also use Glide.

Authentication

Gonduit supports the following authentication methods:

  • tokens
  • session

If you are creating a bot/automated script, you should create a bot account on Phabricator rather than using your own.

tokens: Getting a conduit API token

To get an API token, go to https://{PHABRICATOR_URL}/settings/panel/apitokens/. From there, you should be able to create and copy an API token to use with the client.

session: Getting a conduit certificate

To get a conduit certificate, go to https://{PHABRICATOR_URL}/settings/panel/conduit. From there, you should be able to copy your certificate.

Basic Usage

Connecting

To construct an instance of a Gonduit client, use Dial with the URL of your install and an options object. Dial connects to the API, checks compatibility, and finally creates a Client instance:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

While certificate-based/session authentication is being deprecated in favor of API tokens, Gonduit still supports certificates in case you are using an older install. After calling Dial, you will also need to call client.Connect to create a session. The session key will be stored in the client itself and it will automatically be passed on on every subsequent request.

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		Cert: "CERTIFICATE",
		CertUser: "USERNAME",
	}
)

err = client.Connect()

Errors

Any conduit error response will be returned as a core.ConduitError type:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

ce, ok := err.(*core.ConduitError)
if ok {
	println("code: " + ce.Code())
	println("info: " + ce.Info())
}

// Or, use the built-in utility function:
if core.IsConduitError(err) {
	// do something else
}

Supported Calls

All the supported API calls are available in the Client struct. Every function is named after the Conduit method they call: For phid.query, we have Client.PHIDQuery. The same applies for request and responses: requests.PHIDQueryRequest and responses.PHIDQueryResponse.

Additionally, every general request method has the following signature:

func (c *Conn) ConduitMethodName(req Request) (Response, error)

Some methods may also have specialized functions, you should refer the GoDoc for more information on how to use them.

List of supported calls:

  • conduit.connect
  • conduit.query
  • differential.query
  • diffusion.querycommit
  • file.download
  • macro.creatememe
  • maniphest.query
  • maniphest.createtask
  • maniphest.gettasktransactions
  • paste.create
  • paste.query
  • phid.lookup
  • phid.query
  • phriction.info
  • project.query
  • remarkup.process
  • repository.query
  • user.query

Arbitrary calls

If you need to call an API method that is not supported by this client library, you can use the client.Call method to make arbitrary calls.

You will need to provide a struct with the request body and a struct for the response. The request has to be able to be able to be serialized into JSON, and the response has be able to be unserialized from JSON.

Request structs must also "extend" the requests.Request struct, which contains additional fields needed to authenticate with Conduit.

type phidLookupRequest struct {
	Names   []string         `json:"names"`
	requests.Request // Includes __conduit__ field needed for authentication.
}

type phidLookupResponse map[string]*struct{
	URI      string `json:"uri"`
	FullName string `json:"fullName"`
	Status   string `json:"status"`
}

req := &phidLookupRequest {
	Names: []string{"T1"},
	Session: client.Session,
}
var res phidLookupResponse

err := client.Call("phid.lookup", req, &res)