The new Saasu API platform is here. This initial release provides a basic set of functionality. In time this new API platform will evolve to supersede and surpass the existing API.
First some highlights:
- The new API platform is fully REST based
- It supports content negotiation so you can request data in XML and JSON;
- JSON is the default preferred format
- Attributes are fully supported on invoices
- Attachments are fully supported on invoices
- The existing authentication method (wsAccessKey/FileId) is still supported. OAuth2 is now also supported with time based access token semantics
- Support for Hypermedia, or as the internet loves to call it, HATEOAS
- Documentation is generated automatically by the API itself
The most requested feature by our developer community was the ability to handle attributes on invoices. In the new API we have built attributes in, allowing you to send a complete sale or purchase. For ecommerce platforms you will be able to use attributes for location, colour, size and other stock variants. With the old API you couldn’t interact with attributes at all. Now you can.
The second most requested feature was Attachments. The new API Platform gives you the ability to add an attachment to an invoice allowing use case such as:
- Ecommerce platforms can create a sale in Saasu and attach the PDF the customer received
- Expense apps, you can create a purchase in Saasu for the expense and attach the receipt to the purchase
Pagination is a first class citizen in the new API platform. For responses that return multiple records, it will limit the response to a default number of records (page size) if none is provided. Alternatively you can specify a page and page size to return. We impose upper limits for efficiency. This is also represented in Hypermedia links to show what further paged actions you can make. Combining this with extensive filtering means you can find the data you want efficiently, easily, and fast.
The new Saasu API platform also supports full versioning. This means any future development will almost always be forward compatible. Any additions and changes will not break existing calls. However, in the rare event that we need to make a breaking change to an API call, we will provide access to prior versions of the API call through the use of header values requesting a particular version. This means you can use older versions of the API with older data structures and semantics to enable more time to transition your consumer code to the newer calls.
Also a nice touch is support for Hypermedia. So when you get an attachment, we will show you what other API calls are relevant to the call you are making. You can directly follow the supplied hypermedia links to perform extra actions on the resource being worked with. This is the principle of HATEOAS. It’s worth noting that this feature is not a standard across the industry with many players implementing it in different ways. The support provided by Saasu is a generic format with a view to further refinements as the industry agrees upon a set standard.
The greatest thing is that our work is not ending here. This is the initial public Beta release and we’re already working on adding more endpoints for you to use.
Check out the endpoints available right now:
Invoices (Sales and Purchases)
We have covered every part of an invoice over the API!
- GET lists of sales or purchases
- GET a specific sale or purchase detail
- POST a sale or purchase (create)
- PUT a sale or purchase (update)
- DELETE a sale or purchase
- GET a specific contact
- GET a list of contacts
- GET attachment metadata/information
- GET a specific attachment
- POST an attachment
- PUT an attachment
- DELETE an attachment
- POST a payment
- PUT a payment
- DELETE a payment
- POST a contact
- PUT a contact
- DELETE a contact
- GET a list of accounts
- GET a specific account
Are you excited? We’d love to get your feedback so leave a comment below, email firstname.lastname@example.org or join the conversation on Twitter.