Overview
Avalo Networks provides a general purpose interface layer designed to provide connectivity for UI components. This layer abstracts all of AVP (Avalo Voice Platform) functionality into APIs which provide hooks into the rich internal message bus.
This layer is intended as a lightweight translation providing high level access to the Avalo Voice Platform; however, it is only an example of what can be accomplished using this technology. Use of the AVP APIs is not required by UI designers who may choose to communicate directly with AVP or build their own interface layer.
The AVP APIs can be exposed publicly for other applications but are initially targeted for the AVP UI.
HTTP Methods
Meaning
Not all methods are applicable to for all requests, please consult the API documentation for details.
- GET – Retrieves either a collection of resources or a single resource
- POST – Updates a resource by completely replacing it with the provided data
- PUT – Creates a new resource with the provided data
- DELETE – Deletes a resource
Method Overloading
If your client can not support the necessary HTTP methods (verbs) to interface with the REST API of AVP you can provide the necessary action (PUT and DELETE) in a POST (obviously a GET operates as normal). To override the typical behaviour of such verbs, provide a request body parameter called ‘verb’ with the required method (a query string parameter can be used too).
Example
POST http://api.avpnet.us:{PORT}/v1/accounts/ef7c445e-ff15-11df-8083-43f718c1973c?verb=DELETE
The verb parameter can also be provided in the AVP envelope during POST requests. If the the first occurrence of verb (in order of precedence) is found invalid then processing will terminate.
The order of precedence when both are present is as follows:
- AVP envelope ‘verb’ parameter, in the HTTP content of the request
- HTTP query parameter called ‘verb’, ie: /accounts?verb=PUT
URL Structure
The Avalo Voice Platform API URLs are all based on a generic template:
Base URL
http://api.avpnet.us:{PORT}/v1 |
The base URL for all AVP request will be comprised of these elements.
*http://*, This is the protocol used to make the request.
api.avpnet.us, This is the hostname to the Avalo Voice Platform Application Cloud (AVPAC).
:{PORT}, This is the port that AVPAC is listening to.
/v1, This denotes that the request is intended for the first version of the AVP API
Specifying the Account
Following the base URL most requests will then specify the account that they should operate on.
|
accounts, This specifies the accounts module, and is the base module for all requests except for authorization.
{account_id}, In a request this should be replaced with the complete account_id that the request should be applied to. A typical account id would look like: ‘04152ed2b428922e99ac66f3a71b0215’
Making Request
Typically requests will be made to modules within the account, for example devices. This is done by appending the URL with the module name followed by any resource identifiers.
|
servers, This specifies the server module within the account identified by {account_id}. If nothing follows it then it refers to all servers within the account.
{server_id}, In a request this indicates that the request pertains to a specific server. A typical server id would look like: ‘b2e58f9815e3db4bcc6bf46afee4738b’
deploy, This is a module specific resource component that indicates the request pertains to a parameter of a specific server. Not all modules expose additional access to resources such as this nor are they all the same, see the API documentation for details.
AVP API Request Envelope
When sending requests to AVPAC via PUT or POST the following envelope is expected.
|
Name
|
Optional
|
Description
|
|---|---|---|
| auth_token | yes | Used to provide the auth token when required, and not present in another mechanism |
| verb | yes | Used to override the HTTP method |
| data | no | The request data, provided to the resource |
HTTP query parameters will never be provided to the AVP resources (modules); however, they could conflict with those provided in the envelope. In the event that a parameter is provided in both the request body envelope and the URL query parameters, the request body will be used.
AVP API Response Envelope
When receiving responses from AVP the following envelope parameters are provided for the client.
|
Name
|
Optional
|
Description
|
|---|---|---|
| auth_token | yes | The auth_token will be returned in any envelope if the client provided an authorization token |
| status | no | The status of the request, valid values are ‘success’, ‘fatal’, and ‘error’ |
| error | yes | If an error has occurred this parameter will be the error code, valid values are any integer less than 1000 |
| message | yes | If an error has occurred this parameter will be a description of the error |
| data | no | The response data, from the resource |
Requests/Response Types
Requests
The standard Content-Type header should be used to identify the format of the request body. If the content can not be properly parsed as JSON then the client will receive a 400 Bad Request.
Since some clients will not be able to influence the content type headers the following table indicates both the acceptable content types and the assumed format. In the event that a content type is specified other than JSON, AVPAC will attempt to automatically determine the format.
|
Content-Type
|
Format
|
|---|---|
| text/plain | Automatic Determination |
| text/html | Automatic Determination |
| application/json | JSON |
| application/x-json | JSON |
Response
The response format can be specified in requests using either the Accept header or by extension of the URL. Any extension specified in the URL takes precedence over the Accept header, and if neither is present then JSON is assumed.
|
Accept Header
|
URL Extension
|
Format
|
Default
|
|---|---|---|---|
| application/json or application/x-json | .json | JSON | yes |
JSONP
JSONP can be used when JSON is the response type, and a ‘jsonp’ parameter is in the query string or request body.
For example GET http://api.avpnet.us:{PORT}/v1/accounts/\{account_id}?jsonp=yourJSfun will return:
"yourJSFun({'data': { 'accounts': [...]} });". |
CORS
The AVPAC server is Cross-Origin Resource Sharing enabled enabled. This functionality lets JavaScript in the browser make requests to AVP servers located in a different domain then the JavaScript was fetched from. This is typically forbidden within web browsers by the same origin policy. Modern browsers will all be CORS enabled as well requiring no changes to the JavaScript code.
Filtering
AVP resources can be filtered based on the value or the range of some of its properties. You can accumulate filters on the same resource in order to refine your search. Keep in mind that the corresponding Flex UC module must implement the kazoo_filter module, which is the NOT the default case.
|
Available filters
Some filters are prepended to the name of the property they act upon. For example, the call_id property filter name would be filter_call_id. Other filters are designed to be used as they are, like created_from.
|
Filter
|
Value
|
Notes
|
|---|---|---|
| filter_{property} | Property you are looking for | |
| created_from | timestamp (Gregorian seconds) | Resource created from |
| created_to | timestamp (Gregorian seconds) | Resource created to |
| modified_from | timestamp (Gregorian seconds) | Resource modified from |
| modified_to | timestamp (Gregorian seconds) | Resource modified to |