REST Web Service API

Introduction

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.

In a hurry? Then click on the appropriate links immediately below, else scroll below to get an overview of the guiding principles

API Calls by Business Group

4.1 Customer API
4.2 Orders API
4.3 Invoice API
4.4 Payments API
4.5 Usage Activity API
4.6 Plans API
4.7 Sales Agents and Commisions API
4.8 API Field Limit
4.9 Batch File Upload API

1.General Approach

The established conventions with regard to the HTTP verbs is shown below.

Table 1.1 - RESTful web service mapping [2]

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.

Note: The entities typically use an internal "id" that is a programmatic identifier for the the object and is a globally unique number automatically assigned by the system. They also have a user friendly number (such as invoice number, order number, customer account number, etc.) that is unique for your organization and is designed to be auto-incrementing without gaps (unlike the ids). Usually, the id is not visible to the end user via the application screens, what typically shows is the user friendly number.

Note: For 3rd and 4th column:-Create a customer and validating address of customer by using Avalara API if external tax configuration is enabled. If address validation and customer creation has successfully done then its status will be 200 OK . And if only creation of customer has successfully done then status code will be 201.

2. Security

Authentication

BluBilling utilizes HTTP Basic Authentication for authenticating each API call. A specific "system user" must be created for each client application that will integrate with BluBilling. The userid and password for this system user can then be used when making the API call. Note that the BluBilling application is restricted to communicating using HTTPS with 256-bit SSL certificates, implying that all data including the userid and password are sent encrypted and secured.

Authorization

The application authorizes REST requests only if the security credentials associated with the caller is in the "Web Service Programmatic Access" security role. 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"

Multi-tenancy

The established approach of using the DNS domain prefix (eg: yourcompany.blubilling.com) will ensure that the requested operation pertains to objects owned by the appropriate "tenant" (i.e., Organization). If you get a HTTP 401 (Unauthorized) return code in spite of using a valid userid/password, then chances are that you have provided an invalid hostname/url when performing the API request. All API access is logged and monitored and repeated attempts to access or "scan" entities belonging to other organizations will result in suspension and deactivation of your account per the terms of service.