Requests

Request URLs

Our API servers reside at:

https://api.genability.com

You make requests to a URL that have the following pattern:

https://api.genability.com/rest/v1/{some resource path}

For instance, here are links to get a list of Accounts, and to get one Account using its Account ID, or use your own ID, respectively:

https://api.genability.com/rest/v1/accounts
https://api.genability.com/rest/v1/accounts/genability-account-id-here
https://api.genability.com/rest/v1/accounts/pid/your-own-unique-id-here

Each resource type has a documentation page that denotes the URL that is applicable for that resource. For example, here is the page for Account Tariffs.

Authentication

Each request needs to contain information that identifies you as the client. We have a simple authentication approach in this initial release and will be adding more as we roll out additional API’s. Details here.

Data Types

In addition to standard string and number inputs, we utilize additional input types throughout our APIs.

Array Inputs

Some fields can take multiple values as inputs. These can be specified as a String array. For example the customerClasses and tariffTypes for the Tariff method use this. There are two ways of specifying Arrays as inputs. In these examples we are requesting only "DEFAULT" and "ALTERNATIVE" tariffs:

tariffTypes=DEFAULT,ALTERNATIVE
tariffTypes=DEFAULT&tariffTypes=ALTERNATIVE

JSON Payloads

Data is returned using JSON (Javascript Object Notation). JSON is the only format we support. It’s a lightweight serialization language that is compatible with many different programming languages and technologies. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it. We have no plans to add in other formats (XML, for example) to our standard public RESTful APIs. However, we do handle lots of different formats and integration technologies, just not for our REST APIs.

You should also use JSON in your payload when making HTTP POST and PUT calls that require one.

We do not currently support compression of REST request or response payloads but we do for file uploads and download as part of our HTML API.

For more details of response formats, see the REST Response documentation.

HTTP Methods

The majority of calls to the API will be via HTTP GET since you will be requesting one or more resources. However, some operations require other HTTP methods:

Javascript libraries and some other technologies don’t have an easy way to submit a PUT or DELETE, so we have provided the POST overload. Include a parameter method with a value of PUT (to update) or DELETE (to remove) to get around this.

POST and PUT body

When submitting a POST or PUT request, you will typically supply a body with the request. Here is a description of some of the headers you may need to specify:

Pagination

To help control the quantity of response data returned in a call, we support pageStart and pageCount request parameters. The majority of calls to the API will allow for the use of pagination since you will be requesting one or more resources.

For example, you can fetch the first 100 results by setting pageStart to 0 and pageCount to 100. To fetch the second 100 results, set pageStart to 100 and pageCount to 100.

You can tell how many results matched your query by looking at the count property that is returned in every response back from the API. Note that we currently limit the count property to a maximum of 100,000. You should actually interpret 100,000 as “100,000 or more”. See the Response Payload documentation for an example of a JSON response with the count in it.

Searching and Sorting

Searching for data offers very flexible options for inputs as well as sorting. You can search for text within one or more fields. You can order your results using a prioritized list of fields, each with their own distinction of ascending or descending. Below are the options you can specify when searching, all of which are optional:

Getting Minimum/Standard/Extended Views

In the data definitions for the various objects in the Genability API, you’ll see a “Fields” column for each object property. It can be blank, contain an “E”, or contain an “M”. These values correspond to properties that are in the regular set of fields, the Extended set of fields, or the Minimum set of fields, respectively.

Most requests accept a fields parameter that customizes the data that is contained in the response. For example, pass in a value of min (for minimum) and you will only get a subset of fields in the results you get back. Pass in ext (for extended) and you will get all the fields we make available. “View” therefore modifies the response payload to return data properties flagged as part of the minimum or extended views respectfully. Not passing a fields parameter will return the standard view (so this is the default). The minimum view is designed to make the payload small (and thus quick to load). It’s ideal for situations like building drop-down list or auto complete input boxes. The standard view contains the properties that are commonly used, and is good for showing search results, doing standard computations, and so on. The extended view contains data that is usually not needed but can sometimes be of use.

Using SSL

All API methods should be called over SSL. You must use SSL when working with non-public data such as customer accounts and usage profiles. Make sure your client technology supports SSL (most common REST capable client languages and technologies can).

Compressing Requests

The Genability API supports gzip HTTP compression for API responses. You can enable this feature in your client and immediately enjoy a significant reduction in network traffic. Our official Java client library supports this out of the box.

HTTP Response Compression

To enable HTTP response compression, simply add the following header to your requests:

Accept-Encoding: gzip