README.md

xerogolang (alpha)

This is the Xero Golang SDK for the Xero API.

Currently it only supports the Accounting API.

Xero App

You'll need to decide which type of Xero app you'll be building Private, Public, or Partner. Go to http://app.xero.com and login with your Xero user account to create an app.

Download Xero Golang SDK

Download the SDK using the following command:

$ go get github.com/XeroAPI/xerogolang

Configure

The Xero Golang SDK is easily configured using environment variables to configure values unique to your Application.

The following values need to be set:

XERO_KEY=Your_Consumer_Key
XERO_SECRET=Your_Consumer_Secret
XERO_USER_AGENT=Your_application_name

Find the Consumer_Key and Consumer_Secret you want to use at developer.xero.com under My Apps > Select App > OAuth Credentials.

You must also set a method - this must be either "public", "private", or "partner"

XERO_METHOD=public_private_or_partner

If you are using the "private" or "partner" method you'll also need a Private key path:

XERO_PRIVATE_KEY_PATH=/Path/to/your/privatekey.pem

We include an Example App (in this repo) built using Gorilla.

Example App

This repo includes an Example App mentioned above. The app contains examples of most of the functions available via the API.

To run the example app do the following:

$ cd xerogolang/example
$ go get -v
$ go build
$ ./example

Now open up your browser and go to http://localhost:3000 to see the example.

The example app uses a filesystem store for sessions - you will need to implement your own store when using this SDK within your own app. We recommend Gorilla Sessions

Data Endpoints

The Xero Golang SDK contains the Accounting package which has helper methods to perform (Create, Find, Update and Remove) actions on each endpoints and structs of each endpoint's response. If an endpoint does not have one of the methods then that method is not available on the endpoint. E.g. Branding Themes can only use Find methods because you cannot Create, Update, or Remove them via the API.

Create

Create can be called on structs that have been populated with data:

c := &Contacts{
  Contacts: []Contact{
    Contact{
      Name: "Cosmo Kramer",
    },
  },
}
r, err := c.Create(provider, session)

Find

Find is called either to get a single entity given an id:

i, err := accounting.FindInvoice(provider, session, id)

all entities from an endpoint:

i, err = accounting.FindInvoices(provider, session, nil)

all entities from an endpoint since a specific time:

i, err = accounting.FindInvoicesModifiedSince(provider, session, time.Now().Add(-24*time.Hour), nil)

all entities from an endpoint using paging:

querystringParameters := map[string]string{
  "page": 1,
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint that match a given where clause:

querystringParameters := map[string]string{
  "where": "Contact.Name==\"Vanderlay Industries\"",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint in a particular order:

querystringParameters := map[string]string{
  "order": "DueDate",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint using a filter:

querystringParameters := map[string]string{
  "Statuses": "DRAFT,SUBMITTED",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

a combination of all of the above:

querystringParameters := map[string]string{
  "page": 1,
  "where": "Contact.Name==\"Vanderlay Industries\"",
  "order": "DueDate",
  "Statuses": "DRAFT,SUBMITTED",
}

i, err = accounting.FindInvoicesModifiedSince(provider, session, time.Now().Add(-24*time.Hour), querystringParameters)

Update

Update can be called on a struct containing the data to update. You can only update one entity at a time though.

a, err := accounts.Update(provider, session)

Remove

Remove can be called to remove an entity if you provide an ID - it is not provided on all endpoints though.

t, err := RemoveTrackingCategory(provider, session, "trackingCategoryID")

Acknowledgement

The Xero golang SDK is extended from the great oauth work done by markbates' Goth and mrjones' oauth. We have added support for Xero a provider directly in goth as well so if for some reason you don't want models and methods you can use goth directly.

The gorilla web toolkit is used throughout this SDK and comes highly recommended.

License

This software is published under the MIT License.

Copyright (c) 2016 Xero Limited

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.