What You Will Use
- www.xero.com, especially its APIs
- One of two gems to communicate with Xero API:
- Xero for Developers - documentation for developers which allows them to be more familiar with this solution
- Description of Xero API
- Private applications use 2-legged OAuth and bypass the user authorisation workflow in the standard OAuth process. Private applications are linked to a single Xero organisation which is chosen when you register your application. Access tokens for private applications don’t expire unless the application is deleted or disconnected from within the Xero organisation.
- Public applications use the standard 3-legged OAuth process where a user can authorise your application to have access to their Xero organisation. Public applications can either be web-based or installed on desktop/mobile. Access tokens expire after 30 minutes.
- Partner applications are public applications that have been upgraded to support long-term access tokens.
- allows connecting with Private, Public and Partner APIs,
- allows using the full functionality of API.
- requires SSL certificate (generated by OpenSSL).
Xero Gateway gem
- allows connecting with Private, Public and Partner APIs.
- not all methods are implemented.
Take a look at Xero Getting Started Guide where you can find useful information and a simple guide which allows you to go through an implementation process easily. We are going to use a Xero demo company example because it is a free solution and it's possible to reset it. You can also use the trial version of Xero.com. Here is a link which allows a developer to configure a Xero demo company app: https://developer.xero.com/documentation/getting-started/development-accounts/.
This blogpost might be useful for working with 2 and 3-legged OAuth: What is 2-legged OAuth
In this tutorial, we are going to use a private version of API. It requires generating certificates and is a bit simpler than other kinds of access to API.
openssl genrsa -out privatekey.pem 1024
openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 1825
openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer
You will end up with three files:
Move them to app/certs in your application folder.
Install the gem you prefer (I will show you examples for both of them below)
and run bundle install.
Retrieve Xero API credentials (guide) and place them in your secrets.yml
Step 6: Example Request with Xeroizer
Here is a piece of code with allows a developer to connect with API and return the whole list with which it is rendered inside the view.
Step 7: Example Request with Xero Gateway
Here is a piece of code with allows a developer to connect with API and return the whole list with which it is rendered inside a view
SummaryThe examples above are very simple and show a simple request along with the returned data transformation. The main logic of it is very straightforward and both gems can be used interchangeably.
Among these two gems, I recommend Xeroizer because it allows a developer to work with Xero API easily and has got a nice syntax to invoke different parts of it. Also, it maps every Xero API method into Ruby classes which could be manipulated easily with other things. It's worth to mention that xero_gateway is a wrapper for API.
Exceptions and Unexpected Situations
If you encounter any problems with API, you might be able to find an error at https://app.xero.com/Application/History where you can see the latest queries to API.