Xero SDKs: new releases and updates
The developer evangelist team has been busy since mid-February, when we shared how we are building SDKs for the future. We’ve made lots of updates to our OAuth 2.0 SDKs, and we want to thank all of the developers who are using them and sharing their feedback with us.
Many of our SDK improvements are enabled by improving our OpenAPI 3.0 specifications. We continue to build new specifications for API sets we don’t currently support in our SDKs. Let’s review our progress in the last ~3 months.
OpenAPI specification updates
Our SDKs are generated from OpenAPI 3.0 specifications available on GitHub at Xero-OpenAPI.
Since February, we’ve added AU payroll, UK payroll and projects to our release list. NZ payroll is a close “cousin” to the UK Payroll and shouldn’t be far behind.
In release (being used for building in one or more SDK)
- Accounting
- Bank feeds
- Fixed Assets
- Identity
- AU Payroll (new)
- Projects (new)
- UK Payroll (new)
In development (more testing required)
- NZ Payroll
- Files
Not started (spec to be created)
- Xero HQ
- WorkflowMax/Xero Practice manager (WFM/XPM)
What’s new in each SDK?
Python
Xero’s official python SDK is now available on PyPi.
Our initial release supports the OAuth2 flow, token refresh, the identity API for managing connections and accounting API endpoints. Additional API sets will be rolled out to the SDK in the coming months.
To help developers get up and running quickly, we’ve created a starter app. The code handles the OAuth flow and demonstrates how to retrieve a list of tenant connections associated with an access token, how to refresh your access token, creating a single contact, creating multiple contacts with validation error handling and retrieving a list of invoices filtered by the status.
Like our other SDKs, the codebase can be found on GithHub and we encourage feedback from developers through issues.
Java
There have been 10 releases of Xero-Java since our last blog post moving from version 3.3.0 to 4.1.0. The 3.x releases focused on new API sets and bug fixes.
Support for AU payroll was added and this introduced an interesting challenge. AU payroll API utilizes an uncommon Microsoft JSON date format for dates in requests and responses. We needed a strategy in our SDKs to return native date objects to developers and chose to treat these dates as strings in our OpenAPI specs with no date format. This allows developers to use our specification in other code generators.
We are able to identify these strings during the build process and create two “getter’ methods. For example getStartDate() returns the string /Date(322560000000+0000)/ while getStartDateAsDate() returns 2019–11–12. There are also two setters, but Java allows overriding of the parameters, so setStartDate can accept either a string or a date.
This change in date strategy was applied to our accounting API which forced a major version update to 4.x. We also took advantage of this breaking change to refactor our exception handling, replace floats with double data type and improve logging capabilities. Check out the README for all the details.
Lastly, UK payroll is fully supported with unit tests as of version 4.1.0.
NodeJS
We’ve made 12 releases since our previous update in February as we’ve worked to expand coverage for our Xero-Node SDK, now at 4.6.0 at the time of writing. The XeroClient now offers a disconnect method to facilitate disconnecting a previously authorised organisation as well as an updateTenants method which pulls organisation details for each connected tenant and sorts the tenants list so the most recently authorised organisation is first in the array. Added coverage includes the Assets, Projects, Bank Feeds, and Payroll-AU APIs. Check out our ever-expanding sample app for example usage.
An important note that 4.4.1 introduced breaking changes around XeroClient method naming conventions and an expansion of functionality of non-generated SDK code.
PHP
Our PHP SDK (xero-php-oauth2) tops the charts with 16 releases since mid-February. Many of the improvements have flowed from developer feedback.
Our original plan was to support PHP 7.x and higher, but received feedback that some developers hoped for PHP 5.6 support. We did some testing and made a few adjustments to confirm the SDK runs on this earlier version of PHP.
We received a great suggestion to add interfaces with Countable, IteratorAggregate, JsonSerializable to our objects that return a single array. This was added in version 1.6.0 and refined in the following patches.
The biggest change comes with the release of version 2.x. To make our accounting OpenAPI specifications usable by developers running their own code generators we now define dates as strings with no date format. We are able to identify these strings during the build process and create two “getter’ methods.
$result->getAccounts()[0]->getDueDate()
//returns the string /Date(322560000000+0000)/
$result->getAccounts()[0]->getDueDateAsDate()->format(‘Y-m-d H:i:s’)
// returns 2019–11–12.
We detailed how you’ll need to update your code in the README.
.NET
Now available on GitHub is sample code for .NET Core developers and .NET Framework that demonstrates the OAuth 2 flow and how to make your first API call.
Xero.NetStandard.OAuth2 SDK is out of beta and there have been 11 releases (including 2 majors) since February. From 0.3.0 to 3.0.0, there have been plenty of bug fixes thanks to our developer community feedback. Three more API sets were added to the .NET SDK, including fixed asset, identity and AU payroll.
One piece of great feedback we received from developers is to use decimal data type. So in version 3.0.0 you’ll find decimal instead of double/float for money or any money related numbers. This allows the SDK to have up to 29 digits of accuracy and unlocked handy methods for financial calculations.
The Xero.NetStandardOauth2Client package (v0.0.5) also had some improvements to include a new disconnection method and support for created time, updated time, tenant name and event ID.
The work to get the rest of the API sets into the SDK is already on the way.
Ruby
We’ve made some great progress on the Ruby SDK getting to 1.0 with the addition of the Assets API — this work also included the lion’s share of code that will enable us to roll out the rest of Xero’s API sets in the coming months.
We also released a Rails sample application showcasing strategies to use the SDK for the authentication flow, token refreshing, handling multiple authenticated Xero tenants/orgs, disconnecting tenants and more.
Keep on truckin
We’ve come a long way, but there is still more work to be done. Our goal for 2020 is to have the widest API coverage possible in our 6 SDKs. Your feedback is critical, so please keep it coming.
Keep an eye on the XeroAPI GitHub profile where you can follow our progress. Just because code is generated, doesn’t mean you can’t contribute. We’ve had developers suggest changes that we applied to our templates to solve issues and accepted pull requests on non-generated code.
