Home‎ > ‎Developer's Guide‎ > ‎

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.2 Orders API
      4.3 Invoice API
      4.6 Plans API

1.General Approach

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


RESTful Web Service HTTP methods
Resource GET PUT POST DELETE
Collection URL,Such as 
http://example.com /resources/
List the members of the collection, complete with their member URIs for further navigation. For examle, list all the cars for sale. Meaning defined as "replace the entire collection with another collection". Create a new entry in the collection where the ID is assigned automatically by the collection. The ID created is usually included as part of the data returned by this operation. Meaning defined as "delete the entire collection".
Element URL, such as 
http://example.com /resources/7HOU57Y
Retrive a representation of the addressed member of the collection expressed in an approprite MIME type Update the addressed member of the collection orcreate it with the specified ID. Treats the addressed member as a collection in its own right and creates a new subordinate of it. Delete the addressed member of the collection.

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)

No HTTP Verb and URL pattern Success Response and HTTP status code Failure Response and HTTP status code
1 GET /invoice/234?format=xml Invoice with id=234 in XML format; 200 OK error xml; 404 Not Found
2 GET /invoice/234?format=pdf Invoice with id=234 in PDF format; 200 OK As above
3 GET /invoice?format=xml& invoiceNo=INV2001 Invoice with invoiceNo=INV2001 in XML format; 200 OK As above OR 400 Bad Request if params are invalid
4 GET /invoices?format=xml& startDate=2009-12-01& endDate=2009-12-31 Return a list of invoices between the indicated dates; 200 OK Empty list of ; 200 OK


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.

No HTTP Verb and URL pattern Success Response and HTTP status code Failure Response and HTTP status code
1 POST /orders?format=xml Create a new Order and returns the id in XML format; 201 Created error xml; 400 Bad Request
2 POST /customer/894/salesContact?format=xml Create a new salesContact for the Customer with id-894; 201 Created error xml; 404 Not Found (if not found) OR 400 Bad Request
3 POST /customer/salesContact?format=xml& extCustomerRef=CRM392 Same call as above, except that the business key (extCustomerRef) is provided instead of the id. as above
4 POST /order/345/activities?format=xml Create multiple Activity objects and add them to the Order with id=345 ;201 Created error xml; 404 Not Found (if found) OR 400 Bad Request (atomic operation - either all objects are created or none)


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.

No HTTP Verb and URL pattern Success Response and HTTP status code Success Response and HTTP status code
1 PUT /order/341?format=xml Update order with id=341; 200 OK error xml; 404 Not Found (if not found) OR 400 Bad Request
2 PUT /customer /894/salesContact?format=xml Update the salesContact for the Customer with id-894; 200 OK as above
3 PUT /customer/salesContact?format=xml& extCustomerRef=CRM392 Same call as above, except that the business key (extCustomerRef) is provided instead of the id. as above
4 PUT /order/345/activities?format=xml error xml; 405 Not Allowed (Unsupported by BluBilling) error xml; 405 Not Allowed (Unsupported by BluBilling)


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.

No HTTP Verb and URL pattern Success Response and HTTP status code Success Response and HTTP status code
1 DELETE /order/341?format=xml delete order with id=341; 200 OK error xml; 404 Not Found (if not found) OR 400 Bad Request
2 DELETE /customer /894/salesContact?format=xml Delete the salesContact for the Customer with id-894; 200 OK as above
3 DELETE /customer /salesContact?format=xml& extCustomerRef=CRM392 Same call as above, except that the business key (extCustomerRef) is provided instead of the id. as above
4 DELETE /order/345/activities?format=xml error xml; 405 Not Allowed (Unsupported by BluBilling) error xml; 405 Not Allowed (Unsupported by BluBilling)


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.

No HTTP Verb and URL pattern Success Response and HTTP status code Success Response and HTTP status code
1 POST /order/341?format=xml& action=suspend Suspend order with id=341; 200 OK error xml; 404 Not Found (if not found) OR 400 Bad Request
2 POST /order/341?format=xml& action=generateInvoice Generate an invoice for order with id=341; 200 OK as above
3 POST /customer?format=xml& action=saveCustomerRest Create a customer id=341; 200 OK or 201
as above
4 POST /customer/341?formate=xml&action=updateCustomerRest
Update a customer id=341; 200 OK or 201
as above

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.



3. Error Payload


The error response is usually accompanied by HTTP status code of 400

Sending malformed XML payloads will usually result in this type of response:
<status>
 <success>false</success>
 <errors>
  <error>org.xml.sax.SAXParseException: Closing tag for <customer> not found</error>
  <error>Premature end of file.</error>
 </errors>
</status>


Whereas a validation error will produce these types of response:

<status>
 <success>false</success>
 <errors>
  <error>
    The paymentMethodDTO/paymentMethod/type element must be set to 
    either Cash, ACH, CreditCard or Check
  </error>
 </errors>
</status>                                                                                     

API Calls by Business Group

The following links broadly organize the API calls into distinct groups. 

      4.6 Plans API