The new xero-node SDK

Over a million small businesses, and their advisors are looking for the best cloud apps that integrate with Xero. Partner with us, and we’ll make sure they find yours.

Hi xero-node users and community,

We’re delighted to announce a new version of our nodejs SDK: xero-node v3. It’s a complete rewrite of v2 with a focus on simplicity for you.

We’ve put a lot of thought into the interface and future extensions (*cough* OAuth2 *cough*). The new version brings several improvements and interface changes.

The biggest change is that we’ve removed the entity validation layer of v2. Validation is now handled by Xero’s API instead of the xero-node SDK. This makes it faster and easier for developers to create/update/delete an entity, and reduces the surface area for bugs.

Unfortunately, this does mean a breaking change for developers. We think that the API provides good-enough validation messages and developers should test before production to avoid validation issues.

For example, the code to create an invoice in v2::

// V2
let invoiceObj = xero.core.invoices.newInvoice(invoiceJSON);
let result = await invoiceObj.save();

Looks like this in v3:

// V3
let result = await xero.invoices.create(invoiceJSON);

Much simpler! See our migration guide here for a few other changes.

We understand that the entity validation layer may be important in some cases. If you would like a replacement solution (such as a separate importable module), let us know by posting an issue on GitHub.

Hopefully you’ll notice the simplicity of interface above. We have decided with this convention: xero.{endpoint}.{action}({args}). The actions being get(), create(), update()and delete(). We hope that this will simplify documentation and provide consistency between resource endpoints. This brings into sync Xero’s documentation and the SDK’s interface. For endpoints with a sub-resource the interface looks like this xero.{endpoint}.{subResouce}.{action}({args}) .

For example, a GET on https://api.xero.com/api.xro/2.0/contacts is:

xero.contacts.get();

And a GET on https://api.xero.com/api.xro/2.0/contacts/9a9b2ffd-99c6-40c8-8a83-3d172dabf331/cissettings is:

xero.contacts.CISsettings.get({ ContactID: ‘9a9b2ffd-99c6–40c8–8a83–3d172dabf331’});

The new version is written in TypeScript instead of JavaScript. At Xero, we find that TypeScript increases our productivity and reduces runtime issues. If you use xero-node v3 from a TypeScript project, you will have access to compile-time type-checking. A major advantage will be typed objects returned for anyone using TypeScript. Of course, if you’re using vanilla JavaScript you can still use this SDK with no issues. A recent version of VSCode now gives intellisense for TypeScript modules — even if you’re not using TypeScript!

Another area we have improved is the internal architecture. We aimed to have a clear separation of concerns. This has resulted in 3 layers:

• Accounting API Layer which represents the API endpoints (and all logic for these endpoints)
• BaseAPI (a layer other APIs can extend off e.g. Accounting, Payroll, Files etc)
• HTTP/OAuth (a layer to coordinate OAuth and direct HTTP requests — easily replaced for OAuth2)

We hope this makes it easier to debug issues and add more APIs (the others are coming soon… Let us know what you want, feature requests and PRs welcome!).

Version 3 as the default install when you execute npm install xero-node . Get started by browsing our usage docs and our example end to end tests are a great start.

As for the V2 codebase — we will maintain a branch, accept PRs, and release with the aim of eventually dropping support.

Get involved! V3 has been the effort of a team, so there are several people around to support it (and space for many more). Send us your feedback, thoughts, issues and pull requests on GitHub at xero-node.

The DevX Pod, Xero