JSON API » Introduction
Overview
Enswitch includes a full JSON API to allow 3rd party applications to integrate with Enswitch. The JSON API is capable of everything the Enswitch web interface is capable of, as the web interface uses the JSON API. The API functions provide:
- Authentication. Most functions take an authentication username and password, and check these against the people table in the database. Therefore accounts for API access can be made on the Enswitch web interface under Users and account » Users » Users.
- Checking whether the authenticated user may invoke this function. This is done by checking the person's role and rate plan privileges in the database. For example, users without system owner or reseller access may not call functions affecting other customers, nor will any of the functions they may call return data about any other customers.
- Validation of input parameters. All input data is validated to ensure that it will not corrupt the database. It is of course still the developer's responsibility to ensure that it will not cause problems for the customer in question.
- Database access.
- Any billing required. For example, if a customer calls an API function to create a telephone, the function will add a transaction and update the customer's balance for the telephone creation fee.
- Any other required side effects, such as updating telephone provisioning files.
Accessing the API
The API is not a REST API, but has many of the properties of a REST API. It's accessed using HTTP or HTTPS, depending upon configuration of the Enswitch system. If both are enabled, HTTPS is preferred for security reasons. Clients may use HTTP GET or POST, as they prefer. The base URL is of the form http://<hostname>/api/json/. To this is added a URL path of the form "<category>/<action>" or "<category>/<subcategory>/<action>" or even "<category>/<subcategory>/<subcategory>/<action>". For API functions that manipulate data in the Enswitch database, the "<category>" or "<category>/<subcategory>" normally corresponds to one database table. The actions are typically:
- list: To get a list of such objects for a given customer.
- get: To get the fields of one particular such object.
- create: To create a new object.
- update: To update an existing object.
- delete: To delete an existing object.
Some categories may have other functions. The available functions can be found in the JSON API reference.
Each function has a set of input parameters. These are described in the reference page for that function. Parameters may be passed in the URL in an HTTP GET, or as a form in an HTTP POST. For example, a GET to access the fields of the hunt group with ID 123 might be http://enswitch.example.com/api/json/huntgroups/get/?auth_username=user;auth_password=password;id=123. GET parameters may be separated by ';' or '&'. Authentication information is normally passed in the "auth_username" and "auth_password" parameters (or alternatively an authentication token), and the ID is passed in the "id" parameter. Most functions require the "auth_username" and "auth_password" parameters or an authentication token.
Some functions, particularly those to create objects, have an optional "customer" parameter. This allows you to manipulate data in customers below yours in the customer tree. If you don't specify this parameter, the object will be created in your customer.
The HTTP response will then return a JSON document. The order of fields in the document is not guaranteed, nor is formatting such as whitespace or newlines. The document will include:
- A "responses" element, containing an array of one or more responses. There may be more than one if more than one of the input parameters failed validation tests. Each response will contain a code field, a key field, and a message field. The code field is a number, similar (but not identical) to HTTP error codes, and will always be set. See below for details. The key field may be set, or may be empty. If set, it may be looked up in a local dictionary of error messages to allow an error message to be displayed in the user's own language. The message field will always be set, and will contain an English error message.
- If there is any data to be returned, a "data" element containing the data. If there is, there will typically only be one response, and it will have a code of 200. For list actions, the data element will typically be an array of the fields of each object. For get actions, the data element will typically be a single set of fields of the object. For create actions, the data element will typically be the ID of the new object.
For the hunt group example above, this JSON may look like:
{ "responses":[ { "code":"200", "key":"", "message":"OK" } ], "data":{ "id":123, "name":"example", ... } }
If there's an error, there may be multiple responses, and usually no data:
{ "responses":[ { "code":400, "key":"error_owner_invalid", "message":"The owner is invalid." }, { "code":400, "key":"error_recordgroup_invalid", "message":"The record group is invalid." }, ] }
The following response codes are in use:
| Code | Description |
|---|---|
| 200 | Success, and data is being returned. |
| 201 | Input passed validation. Only returned if validation=1. |
| 204 | Success, and no data is being returned. |
| 400 | Invalid input parameters specified. Check the key and message fields for more details. |
| 401 | The authentication details provided are invalid. |
| 402 | Your role does not allow this. |
| 403 | Your rate plan does not allow this. |
| 404 | The object does not exist, or you do not have permission to view it, perhaps because it's in a customer you don't have access to. |
| 500 | An error occurred within the server. Check the key and message fields for more details. |
The reference page for each function will list the response codes used by that function, and will include usage examples.
Switching user
Sometimes it can be useful to invoke an API function as a different user, perhaps in a different customer. If you have suitable permission, you can do this without knowing the user's password. This can be done by setting the auth_username parameter to "<your username>|<the username you wish to switch to>". The API function is then executed as the user you've switched to. For example, if your username is "alice" and you wish to run the API function as user "bob", set auth_username to "alice|bob". If you wish to switch to a customer's pseudo-user, use the customer's name in square brackets - for example "alice|[Test customer]". You may only switch to users if you have administrator access and the user you're switching to is in the same customer, or you have reseller access and the user you're switching to is in a customer beneath yours in the customer tree. Set the auth_password parameter to your own password, not the user you're switching to.
Logging API calls
If you enable the "api" level in the logging, all API function calls and returns are logged. This can be useful for debugging purposes. Note that this may use a lot of disk space on busy systems. Passwords are logged as "[hidden]" for security reasons.
Enswitch upgrades
Every new version of Enswitch makes changes to the API. These are documented at the bottom of the reference page for each function, and a running summary is also kept.
Most changes should not adversely affect API users, and are typically adding new functions, adding optional input parameters to existing functions, and adding new fields to the JSON returned. API clients must be able to gracefully cope with the server accepting new optional input parameters or the server sending new fields in the JSON returned, even in the middle of stable versions.
Sometimes it's necessary to make API changes that require client changes. Such changes will be kept to a minimum. If any are necessary, these are documented at the bottom of each function's reference page and on the summary page. The summary page will highlight any such changes, so you should check the summary page before upgrading Enswitch.