Getting Started


Rest API Release 1

Welcome to the aBILLity REST API reference. REST API is used to help developers to integrate their systems with the Portal. It provides building blocks to programmers in order to create their other systems that can access Portal back end. Explore the FAQ and Samples to get started.

Key Features

  • Utilises the Portal Permission Framework
    • Authentication for use of the API requires a valid username and password.
    • The data returned by the APIs is restricted based upon the access rights of the username used to connect to the API
      i.e. A user with no permission to view Billing Information will not receive any returned data from a get Billing Information call.

  • Customisable Help Documentation
    • Content of the various pages i.e. Getting Started.
    • Branding i.e. The Styling and Logos used for the sites look and feel.

  • Reference detail is automatically created for new methods or relevant changes to existing methods
    • Additional Information for the reference detail can be customised
      i.e. explanation text for each API call or for each field available for a call.

 

Authentication

Authentication is through the use of a valid username and password obtained from a system administrator and should be a valid username and password on the system. Each API call should include these as HTTP header fields, together with another field called SystemInformation to identify the correct REST API system. See Samples here

Available API methods

Frequently used entities such as Company, Site and Service Charges are available from the API as methods. The full list is available here.

Requests and Responses

For the simplicity and usability, the URL of the request governs the resource that is being called: for example, A GET request URL api/contract/{id} is used to get a specific contract for the given id. All API requests should include header information as described in Authentication page. Where appropriate, for some methods you can define paging and sorting as well (see Contract GET method). Responses are standard HTTP objects, allowing the caller to get their content either in XML or JSON. Samples page shows both these formats for each available method.

Functionality

API Methods to Add Content Supporting Read Methods
Company Bill Run
Site Report Profile
Site Contact Payment Method
Billing Information Tax Codes
Invoicing Information Invoice / Report Delivery
CLI CDR / Service Format
Sell Tariffs Frequency Type
Service Charges  
Service Charge Types  

Pagination, Sorting and Searching

The API uses pagination, searching and sorting to limit the response size for methods that return a potentially large collection of items. The request can include following parameters: search_text, page_no, sort_column, sort_direction and page_size. Such request to a paged method will result in a values array wrapped in a JSON/XML object with some paging metadata.

For example: Request /api/cli?search_text=07111111111&page_no=1&sort_column=my_id&sort_direction=asc&page_size=1 will search for clis containing "07111111111" and return the first page of the resultset after splitting the results into pages of 1 record per each.
<Response xmlns="http://test01-web01.devops.local:61441/api/cli"> <Count>1</Count> <CurrentPageNumber>1</CurrentPageNumber> <SortColumn>my_id</SortColumn> <SortDirection>asc</SortDirection> <cliList> <e> <CLI>07111111111</CLI> <EndDate null="true"/> <Id>2</Id> <LineType null="true"/> <SiteId>6</SiteId> <StartDate null="true"/> <TariffInfo> <SellTariff null="true"/> <ServiceChargeSellTariff null="true"/> </TariffInfo> <UserName null="true"/> </e> ... </cliList> </Response>

Error Messages

Although an API call is well-formed, it can be rejected due to business rules. In these circustances, a meaningful error message will be returned. For example:
{"Message":"The request is invalid.","ModelState":{"Orders.CompanyId":["No company found with id = -1"]}}