Accessing the Xero API for Public Applications in Java

In this post I’ll quickly run through accessing the Xero API using Java and the super simple, elegant Scribe library. There’s a support page dedicated to Java + Xero API but I found it a bit light on help for those setting up a public application for the first time in Java, so the below steps should help others wanting to get up and running. For the actual access to Xero we’ll be using Ross Jourdain’s excellent Xero library, which handles mapping the XML into Java objects for you. I’ve made a couple of tweaks to it to support App Engine, and Scribe. I have also set up a XeroApi and XeroExample in the Srcibe format, for use with the library.

The other reason you might like these instructions rather than the default, is that we run our apps on Google App Engine for Java and so we had to make a few changes to the way we access Xero in order to meet the GAE requirements. The Scribe library supports GAE out of the box.

Why am I mucking about with the Xero API, anyway? We’re working on an app that connects Xero with Amazon for merchants to import accounting data automatically. I’m not quite ready to tell the world about it, but if you’re interested in trying it, get in touch.

Let’s get started with the Xero API, a public application, and Java!

Set up your public application

Xero has a very clean simple interface for API access, you manage your applications here https://api.xero.com/Application. You’ll want to create a new application by clicking the Add Application button.

You’ll need to give the application a name and URL for informational purposes. The callback domain is important, you’ll want that to be the domain that your application is running on, so for example yourapp.com, or if you’re testing locally, localhost.

One tip I’d add here, create two public apps, one for real, and one for testing then you can have a different callback host like localhost for the test app, and then you can configure your application to use the correct credentials for the environment it’s running in.

For example in Google App Engine you’d do something like this:

private static XeroCreds getCreds() {
 
	if (SystemProperty.environment.value() ==
			SystemProperty.Environment.Value.Production) {
		return XeroCreds.PROD;
	} else {
		return XeroCreds.TEST;
	}
}

The oAuth dance

Right, so we have our application, now we need to prompt the user for authorization – and do the oAuth dance.

You can see in the example I published on github, the Sribe library makes it super easy to set up for a Xero public application. Use the XeroApi.class class also provided.

OAuthService service = new ServiceBuilder()
                .provider(XeroApi.class)
                .apiKey(API_KEY)
                .apiSecret(API_SECRET)
                .build();
 
Token requestToken = service.getRequestToken();
String url = service.getAuthorizationUrl(requestToken);
 
// user goes to the URL and gets the verifierString
Verifier verifier = new Verifier(verifierString);
 
// Now you can get an access token - persist this to reuse it for 30 minutes
Token accessToken = service.getAccessToken(requestToken, verifier);
 
// Make an actual request
OAuthRequest request = new OAuthRequest(Verb.GET, PROTECTED_RESOURCE_URL);
service.signRequest(accessToken, request);
Response response = request.send();

That’s it, simple right? If you run the example on the command-line you’ll be able to easily test this with your own credentials and endpoint. The problem is this response.getBody() has a big mess of XML, we’ll want to do something constructive with that. Which is where Ross Jourdan’s Xero Java library comes in handy.

Making actual requests for XML

Using the Xero API library for private applications works great, to make it work with public applications using Scribe, we need to make a few tweaks. The main difference is that private applications use signed requests, where as public applications require the access tokens from a user who has authorized your application.

Using my slightly tweaked version of Ross’ library we can subclass the default XeroClient to change the oauth accessor, and also in the case of Google App Engine compatibility, we can inject our own HttpClient and extra invocation parameters.

Depending on your needs you would create subclass something like the below:

public class MyXeroClient extends XeroClient {
 
	public MyXeroClient(String endpointUrl, String consumerKey, String consumerSecret, Token accessToken) {
		super(endpointUrl, consumerKey, consumerSecret, "");
		this.accessToken = accessToken;
	}
 
	protected HttpClient getConnectionClient() {
		URLConnectionClient urlConnectionClient = new URLConnectionClient();
		return urlConnectionClient;
	}
 
	public OAuthAccessor buildAccessor() {
		OAuthConsumer consumer = new OAuthConsumer(null, consumerKey, consumerSecret, null);
		OAuthAccessor accessor = new OAuthAccessor(consumer);
		accessor.accessToken = accessToken.getToken();
		accessor.tokenSecret = accessToken.getSecret();
		return accessor;
	}
 
	protected List<Parameter> addExtraParams(List<Parameter> currentParams) {
		//add your extra HttpClient configuration here
	}
}

And then you can make your actual requests to Xero with this new client, and deal in Java objects instead of messy XML.

MyXeroClient xeroClient = XeroUtil.getClient(acct);
ArrayOfAccount accounts = xeroClient.getAccounts();

And that’s it, full Xero public application accessing the API via Scribe on Google App Engine.

Now what?

With only a 30 minute lifetime on the oauth access tokens, for any useful application you’ll probably need to get upgraded to a partner app. You can apparently do that by contacting Xero, which is what I’ll be doing now! Will report back on that process here later.