— Please note (updated May 2017) —

Invoices on REST have been fully migrated to stable. Invoice data is accessed using the /invoices endpoint.

———

When we first set out to create a REST API the first proof of concept was the /invoices endpoint. It was the endpoint we chose to expose while setting up the production environment and getting our feet wet. Like always the first steps are where you learn and where you discover what not to do. We decided that the only thing worth reusing from that endpoint was the experiences we made.

So we decided to create a new endpoint to replace the old /invoices endpoint. The new endpoint has now reached a point where we feel it is safe for production consumption. It is stable and conforms to our coding style. So what does that mean for you? Two things:

1) You get added value with the new /invoices endpoint in the form of new functionality and a simpler model

2) You need to switch your apps to the new endpoint using the migration path we have created

More details on these two points below. But first, a big thank you to everyone who has used the old endpoint. By doing so you have helped us so much and provided us with very valuable usage statistics and feedback.

Added value by moving to the new /invoices endpoint

With the new endpoint, we set out to create a simpler model and interface. This means that the representation of an invoice is now a single document. This way you can create a full invoice including lines in a single transaction. So if there is a problem with one line, then the whole invoice is rejected. In SOAP and the old deprecated /invoices endpoint you would have to clean up after yourself if something like this happened.

Creating a simpler model also means providing functionality to avoid magical defaults. Using the old SOAP create methods meant that you would get all defaults set on a new invoice.

To make this more transparent we have introduced templates. These templates allow you to get those defaults in a document and edit them, if necessary, before you create them. Again, this allows you to create invoices in a single transaction and still get all the defaults that add so much value. You can read more in this blog post on template functionality in REST.

We have also implemented invoice totals that allow you to easily access totals for invoices and also deep dive into some light statistics on invoices. These totals are perfect for creating cool and dynamic dashboards. Learn more about the invoice totals endpoint in this post.

Another really cool new feature with the new /invoices endpoint is the support for annotated errors. This makes the job of figuring out why an operation failed much easier. Read more about annotated errors in our REST Docs.

Finally, to make it easier to relate an API invoice resource to what you see in the e-conomic web UI, we have also changed the identifier to be what you see in the UI, instead of using the same ID as SOAP like the old /invoices endpoint did.

But don’t worry, we still display the old SOAP ID to make it easy for you to migrate from SOAP to REST. Simply use this “SOAP” property that contains the SOAP ID: soap.currentInvoiceHandle.id. You can of course filter on this property: https://restapi.e-conomic.com/invoices-experimental/drafts?demo=true&filter=soap.currentInvoiceHandle.id$eq:81

How to switch your apps to the new endpoint

In order to give consumers of the REST API a chance to switch over gracefully, we have created a migration path.

The migration path consists of three stages. In all three stages there is one central endpoint that changes behavior in each stage. That is the /invoices endpoint.

Each stage in the migration path holds some action points if you use the deprecated /invoices endpoint.

Stage 1 (June 1st to September 1st)
The first stage is where we are at the time of writing this blog post. The /invoices endpoint still exposes the deprecated contract and functionality. There is also an aliased endpoint that exposes the same functionality. This endpoint is /invoices-deprecated.

Action points for stage 1:

• First you need to change your code to start using the /invoices-deprecated alias. That way your application won’t break when we change the functionality of /invoices.
• Then you need to start looking into refactoring your application to use the new functionality exposed by /invoices-experimental. You should check out the documentation found here and see the sections on new functionality above. Make sure it is easy for you to change from using /invoices-experimental to /invoices when we change that functionality.

Stage 2 (September 1st)
In the second stage we change the functionality of /invoices to be the same as on /invoices-experimental. This means that if you haven’t changed over to use the /invoices-deprecated endpoint your app will break.

Action points for stage 2:

• If you have already refactored your code to use /invoices-experimental you should now change your code to use /invoices instead. This also means that you are done, and your migration is finished.
• If you haven’t refactored your code to use /invoices-experimental, now is the time. But just go ahead and refactor to use /invoices. Again the resources you should look into when doing that are in the three links found under Stage 1.

Stage 3 (January 1st 2017 or when usage flatlines)
The last stage is where we clean up after the migration. We delete the endpoints /invoices-deprecated and /invoices-experimental, leaving only the new /invoices endpoint available. If you still haven’t migrated at this point, your app will break.