xero-node version 3

[philals]

Hi xero-node users and community,

A new version of xero-node is coming. We have been working on it for a few weeks, and the team has recently spent a few days mobbing it.

There were a few issues we wanted to address, which I'll outline below.

The biggest change is to remove the entity validation layer of V2. Many of the issues and pull requests in V2 are related to entity validation. Removing the validation step makes maintenance less demanding, and also improves performance by reducing the number of method calls developers have to do when creating an object within Xero. We think that Xero's API provides good-enough validation messages and consumers should be testing before production to avoid validation issues.

Unfortunately, this does mean a breaking change to consumers. We spent a time thinking about error messages and exceptions, so we think it's worth it.

Example:

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

becomes:

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

Much simpler! See here [[for our migration guide]].

We have a few ideas for pre-validation, if the community wants it, such as a separate importable module that replicates Xero's API validation logic. But we want this SDK to be as thin as possible.

Hopefully you'll notice the much simpler interface above. We have gone with this format
xero.{endpoint}.{action}({args}). The actions being get(), create(), update(), delete(). We hope that this will simplify documentation and provide consistency between resource endpoints, Xero's documentation and the SDK's interface. For endpoints with a sub-resource the interface will looks like this xero.{endpoint}.{sub-resource}.{action}({args}).

A good example of this is Contacts.

xero.contacts.get() is a GET on https://api.xero.com/api.xro/2.0/Contacts/
xero.contacts.CISsettings.get({ ContactID: '9a9b2ffd-99c6-40c8-8a83-3d172dabf331'}); equates to https://api.xero.com/api.xro/2.0/Contacts/9a9b2ffd-99c6-40c8-8a83-3d172dabf331/cissettings

We used TypeScript (we use it internally at Xero). We find this increases our productivity and even reduces run time issues. A major advantage will be types objects begin returned for anyone using TypeScript. Of course, if you're using vanilla JavaScript you can still use this SDK with no issues.

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

• Accounting API Layer (all logic related to endpoints etc)
• BaseAPI (a layer other APIs can extend off eg, Accounting, Payroll. Files)
• HTTP/OAuth (does OAuth and makes HTTP requests)

We hope this makes it easier to debug issues and extend for other APIs (the others are coming soon..).

We have also given thought to OAuth2. The underlying OAuth library is OAuth2 compatible. When OAuth2 comes we will just need to write a new HTTP/OAuth layer for the BaseAPI to consume.

We are now at a point where we'd love to hear your feedback and thoughts.

V3 has been the effort of a team, so there are several people around to support it. If you want to get involved we're more than happy for the help. Development has been going on over here: https://github.com/XeroAPI/xero-node/tree/v3

The plan from here on is take this branch into master. For the V2 codebase - we plan to maintain a branch, accepting PRs and doing releases with the aim of eventually dropping support.

We have released a @next version. See below.

[philals]

We have started publishing the newest version and will do as often as we can.

To install run

npm install xero-node@next

To see the lastest alpha version run this command: npm show xero-node versions

[philals]

Hi.

Thanks to our beta users. We have released V3 out of beta.

There might be a few changes for you:

1. The Organisations method is now organisations with an S
2. contactGroups is now camelCase rather than contactgroups
3. expenseClaims is now camelCase rather than expenseClaims

Thanks again for the feedback.

There is a quick write up here: https://medium.com/@phil.alsford/the-new-xero-node-sdk-2c69dcab4a2f

@ashishsrivastavaicreon
@rjaus
@timelincoln7648
@danielmoi
@DaveCLowe