IntroductionBluSynergy 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 1.General ApproachThe 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)
|
| 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> |