Some time ago we decided that our e-conomic API offerings needed to improve. Our SOAP API is robust and quite extensive with regards to the features offered. In its basic architecture, however, it is not very well structured or approachable for mere mortals. The API requires a lot of domain and application knowledge from its consumers, i.e. partners and developers.
This is what we set out to fix.

The solution: Our REST API – which is currently being developed and matured.

As opposed to the SOAP API, which is made up of small atomic pieces, we want to take full advantage of the benefits provided by a document-based REST API. That means that when creating a draft invoice, for example, you specify the entire invoice, including lines and everything else, as opposed to creating each part of the invoice separately. The benefit of that approach is that if one line fails to be created, then the whole invoice is rejected and you won’t have to clean up “orphan” invoices before you can try again. Another clear benefit to this is that you can do the same work using fewer requests.

Additionally, the document-based approach provides accessibility. The documents are easily read by human eyes, and if you have a browser extension installed that formats JSON for you, you can easily navigate the API using nothing but your browser and the links provided by the API. The REST API is hypermedia-driven and provides links to all resources. So you should never have to construct any URL yourself. These should be provided by the API.

Try installing an extension like this one (for Chrome), and navigate to the root of our API at https://restapi.e-conomic.com. You will see a number of links as well as metadata about the API. But if you follow a link to one of the collections, such as https://restapi.e-conomic.com/customers, you will get an error response stating that you do not have access. In that response is a new link that will give you access to demo data. When following that, all the subsequent links will point to demo data.

This is an invaluable resource when exploring and working with the API.

REST documentation

We are painfully aware that the documentation for our old SOAP API leaves a lot to be desired. That is why we have decided to treat documentation as a first class citizen. We are working actively on creating schemas for all the endpoints we expose. This allows us to easily document property dimensions and other useful information, something that was never available for the old SOAP API.

Combining this with a structured documentation site, based on Slate (https://github.com/tripit/slate) means that we can easily add to and evolve the API documentation as needed.

We also try to make error messages much more descriptive and useful than what you have been used to from the old SOAP API. This includes adding developer hints and meaningful descriptions along with unique error codes when a request is rejected. The response you get from us is always the first place to look for documentation.

Check out our documentation portal here!

We auto-generated as much of the documentation as possible from our JSON schemas. So the documentation will always be in sync with the actual endpoints.

What we are working on

Our roadmap for Q2 of 2015 is all about supporting sales invoicing. We want our API to support most of the ‘vanilla’ use cases for creating customer invoices, editing them and finally booking them. This includes exposing the underlying data required to do this, i.e. customers, products, layout and much more.

Specifically, we are working on maturing these endpoints:

• /invoices/drafts
• /invoices/booked
• /customers
• /products
• /layout
• /units
• /payment-terms

We will also implement elements of some our add-on modules as we progress through the various endpoints. For instance, the response on a GET on /products/:id will include properties related to the Inventory module. That doesn’t mean that we are complete in our support for inventory on the REST API (we aren’t). But we are ‘peeling the onion’, so to speak, as we are progressing through each endpoint.

Another thing we are working on is the option to add documents to vouchers. A voucher is specific to agreements utilizing our ‘International Ledgers’ instead of the (at least for Denmark) more common day book ledger type. More info on this will follow in later TechTalk posts.

The future of the SOAP API

Our SOAP API is still a valuable offering to all our partners and developers. It is used in 300+ production solutions and is vital for extending e-conomic core features to external partners. Therefore, it will not be deprecated any time soon. We’re committed to fixing critical bugs and otherwise maintaining the current feature footprint. We will, however, not be extending the features offered in SOAP to any larger degree.

Our .NET SDK has been deprecated, and we urge developers to interface directly with the SOAP API instead. The reason for this is that it is a big task to maintain both the API and the SDK, and the SDK does not add any additional value. So we have removed the download site and all mentions of the SDK in our documentation.

We welcome your comments and suggestions for improvements, so please drop us a line or leave a comment below.