The BluSynergy eBill suite 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. Skip to the bottom of this page, to get to the API calls organized by business entity.
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
https://example.com /invoices/ | 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
https://example.com /payment/12345 | 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 - eBill 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 /customer?format=xml | Create a new Customer 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 eBill 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 /invoice/341?format=xml | Update invoice 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 eBill) | error xml; 405 Not Allowed (Unsupported by eBill) |
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 eBill) | error xml; 405 Not Allowed (Unsupported by eBill) |
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
|
