The Xero API Analysis

Today we’re going to take a look at the Xero API as part of our analysis of the ASX100’s APIs. In the long run, we’re making an effort to understand what best practice looks like in the wild.  

This post isn’t a strict analysis – this will come in a later post. Instead, I’m going to provide commentary as I step through the Xero API, building on the approach taken to analysing the NAB API. 

We’ll cover both product and technical aspects of the API, so this will hopefully be relevant to both product, UX and technical folks.

First Impressions and Portal Home Page

I was immediately impressed by the inspiration of the home page. “Make apps for 2 million small businesses”.

Next, I was left with a feeling of confidence that I’d be able to easily start using the API thanks to a little snippet on how to get setup: “Signup for a free Xero account. Use our getting started guide to get up and running as quickly as possible.”

I was also able to browse documentation without signing up.

The audience for the Developer Portal and API seems somewhat clear. You’re building a marketplace app to distribute, or you’re building something on Xero for others. What I felt was missing is “build for my organisation”. It’s probably the same as building for others, but there is a market of people that will want to make their own apps/integrations (maybe Xero feels this is captured in that they see that most people engage a developer to build their integration for them). 

Registration

The process to register was:

1. Sign up with a Xero account
2. Confirm my email address
3. Enter a password
4. Click “Try the Demo Company” 

The Demo Company being featured prominently is a nice touch for developers looking to get started (I’m sure it’s useful for new users as well). It meant I was ready to interact with real data within 3 minutes of starting the sign-up process.

Getting Started

Despite having seen the link earlier on getting started, I did get momentarily confused when trying to get started. I had to find the link again after trying to find “getting started’ in the top menu nav. The Ways to Build was somewhat meaningful, but perhaps “Getting Started” might be better as a top menu nav. I did find the Getting Started link again quickly, so not a major issue. 

I was able to query the actual data in my account (the Demo Company) with the Xero API Previewer within 2 minutes. In practice, the ability to run a real query on real data this fast can be the difference between whether an engineer chooses to build against your API or whether a customer chooses your product/solution. Being able to check out how the API really works with real responses from the browser without firing up an IDE or dealing with OAuth problems is so important in designing an integration or solution built on an API.

API Documentation

The API is nicely grouped by the various features you might need to interact with.

After clicking on the area you are interested in, you can drill down. Drilling down shows takes you to a list of the types of data/objects (e.g. Transactions, Budgets, Contacts, Invoices) you might want to interact with. 

The API is documented in a fairly comprehensive list of languages: C#, Java, NodeJS, PHP, Python and Ruby. You can also access the OpenAPI spec.

API Design

URL Standard

The Xero API follows the RESTful standard closely, using HTTP verbs to describe the action being taken – GET – and the URL to describe the resource the action is being applied to (e.g. GET http://…/Invoices).

Variable/Parameter Names

The variables names and parameters for the Xero API were easy to follow. They used full names and had detailed, useful descriptions against most items.

Variables with acronyms were well described. E.g. CISDeduction withheld by the contractor to be paid to HMRC on behalf of subcontractor (Available for organisations under UK Construction Industry Scheme).

Versioning

Versioning was used in the URL (e.g. https://api.xero.com/…/2.0/Invoices).

Going Live to Production

Running your code against production data only takes a few minutes more than the registration and getting started. The Demo Company you are querying is technically production data, and there isn’t a staging or sandbox environment that you work with. There are instructions on how to work with the OAuth process that are easy to follow. 

Community

There is an active developer community, with online comments as recent as two days ago (as at the time of writing). 

Product Strategy

After the deep dive into the API, I want to briefly reflect on Xero’s API in the broader lens of their product strategy. Some thoughts: The API is easy to work with. This ease is a clear enabler for third party products and developers to help businesses automate their accounting/finances, thus strengthening Xero’s stickiness and functionality/features they can offer.

---