BluSynergy offers a contemporary REST based API that is agnostic of any programming language or operating system. Please refer to these three introductory sections about general usage patterns and programming practices before commencing development.
The established conventions with regard to the HTTP verbs is shown below.
Content Negotiation – BluBilling will use a “format” request parameter to indicate the format. In the future, this may be extended to the ACCEPT or CONTENT_TYPE HTTP headers as well. The ContentType will be set appropriately (application/pdf, text/xml, etc.) by the application for the return.
Retrieve Examples (HTTP GET):
Note that when a multiple entities are expected, the URL maps to the plural form (eg “invoices” with a “s” at the end).
Create Examples (HTTP POST):
Note that when a multiple entities are expected to be created in a single call, the URL maps to the plural form. Note that all calls are atomic from a transactional standpoint.
Update Examples (HTTP PUT):
In the case of an update, the payload needs to contain the entire object graph and not just the changed values. In the use cases for BluBilling there is not a significant need for bulk updates, so only individual objects (along with their child objects) may be updated.
Delete Examples (HTTP DELETE):
Delete operations are specified by id and in some cases by the unique business key. Currently, bulk deleted are not supported.
Complex Cases (HTTP POST):
In cases where the desired operation is an action, the REST approach has its deficiencies (when compared to SOAP). These cases are handled by a POST operation with an “action” query string parameter to indicate the desired operation. Additional parameters required by the operation are passed in the XML request payload. The result of the operation may return one or more objects depending on a case-by-case basis.
Since the entire application will be restricted to HTTPS, the use of basic authentication in conjunction with the Spring Security (aka Acegi security) is used for BluBilling. This implies that all REST requests will be stateless.
Authorization will be performed by requiring a security role called “ROLE_API”. Controllers will enforce that any REST request (format=xml) is served only if the caller is in the ROLE_API. A new user may be created with this security role by using the “System >> Staff Members” menu. Be sure to set the security role on this screen to“Web Service Programmatic (API) Access”
The standard approach of using the DNS domain prefix (eg: acme.blubilling.com) will ensure that the requested operation pertains to objects owned by the appropriate “tenant” (i.e., Organization is the case of BluBilling).
The error response is usually accompanied by HTTP status code of 400
Sending malformed XML payloads will usually result in this type of response:
Whereas a validation error will produce these types of response:
Hosted self-service pages allow you to embed the “My Account” functionality from BluBilling into your own website. This allows your customers to perform self-service activities such as view their account balances and status, current and past invoices, make payments, etc. All of these self-service screens are already built into BluBilling, and may be quickly deployed within a framed page on your own website so that you maintain brand presence with your customer by keeping them on your own website.
There are two approaches for deploying the BluSynergy Self-Service Portal inside your website:
Webhooks (also known as “web callbacks” or “outbound push notifications”) are sent by the BluSynergy system when specific business events occur. These are typically used when your application needs to be notified that billing or payments related events have occurred. These settings may be configured from the [System >> Integration Settings >> Website Callbacks] menu.
For example, let’s say you’d like to automatically provision a user account in your application/systems when a new customer is created and you’d like to de-provision/suspend the account if a customer is delinquent. In this case, you’d select the “New Customer Signup” and the “Customer Status Change” events. Now, all subsequent customer signups and customer status changes will cause the BluSynergy system to initiate a Webhook request to your system.