XiVO REST API

The XiVO REST APIs are the privileged way to programmatically interact with XiVO.

Reference

For other services, see http://xivo/api/. This public instance does not allow you to directly test the requests (i.e. the “Try it out!” button will not work), but you may use the embedded version of your XiVO, where this button will work.

Access

Each REST API is available via HTTPS on different ports.

Examples (xivo-confd)

# Get the list of users
curl --insecure \
-H 'Accept: application/json' \
-H 'X-Auth-Token: 17496bfa-4653-9d9d-92aa-17def0fa9826' \
https://xivo:9486/1.1/users

# Create a user
# When sending data, you need the Content-Type header.
curl --insecure \
-X POST \
-d '{"firstname": "hello-world"} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: 17496bfa-4653-9d9d-92aa-17def0fa9826' \
https://xivo:9486/1.1/users

Authentication

For all REST APIs, the main way to authenticate is to use an access token obtained from xivo-auth. This token should be given in the X-Auth-Token header in your request. For example:

curl <options...> -H 'X-Auth-Token: 17496bfa-4653-9d9d-92aa-17def0fa9826' https://<xivo_address>:9486/1.1/users

Also, your token needs to have the right ACLs to give you access to the resource you want. See REST API Permissions.

See also Service Authentication for details about the token-based authentication process.

Other methods (xivo-confd)

Warning

DEPRECATED

For compatibility reason, xivo-confd may accept requests without an access token. For this, you must create a webservices user in the web interface (Configuration ‣ Management ‣ Web Services Access):

  • if an IP address is specified for the user, no authentication is needed

  • if you choose not to specify an IP address for the user, you can connect to the REST API with a HTTP Digest authentication, using the user name and password you provided. For instance, the following command line allows to retrieve XiVO users through the REST API, using the login admin and the password passadmin:

    curl <options...> --digest --cookie '' -u admin:passadmin https://<xivo_address>:9486/1.1/users
    

HTTP status codes

Standard HTTP status codes are used. For the full definition see IANA definition.

  • 200: Success
  • 201: Created
  • 400: Incorrect syntax
  • 404: Resource not found
  • 406: Not acceptable
  • 412: Precondition failed
  • 415: Unsupported media type
  • 500: Internal server error

See also Errors for general explanations about error codes.

General URL parameters

Example usage of general parameters:

GET http://<xivo_address>:9486/1.1/voicemails?limit=X&offset=Y

Parameters

order
Sort the list using a column (e.g. “number”). See specific resource documentation for columns allowed.
direction
‘asc’ or ‘desc’. Sort list in ascending (asc) or descending (desc) order
limit
total number of resources to show in the list. Must be a positive integer
offset
number of resources to skip over before starting the list. Must be a positive integer
search
Search resources. Only resources with a field containing the search term will be listed.

Data representation

Data retrieved from the REST server

JSON is used to encode returned or sent data. Therefore, the following headers are needed:

  • when the request is supposed to return JSON:
    Accept = application/json
  • when the request’s body contains JSON:
    Content-Type = application/json

Note

Optional properties can be added without changing the protocol version in the main list or in the object list itself. Properties will not be removed, type and name will not be modified.

Getting object lists

GET /1.1/objects

When returning lists the format is as follows:
  • total - number of items in total in the system configuration (optional)
  • items - returned data as an array of object properties list.

Other optional properties can be added later.

Response data format

{
    "total": 2,

    "items":
    [
        {
            "id": "1",
            "prop1": "test"
        },
        {
            "id": "2",
            "prop1": "ssd"
        }
    ]
}

Getting An Object

Format returned is a list of properties. The object should always have the same attributes set, the default value being the equivalent to NULL in the content-type format.

GET /1.1/objects/<id>

Response data format

{
   "id": "1",
   "prop1": "test"
}

Data sent to the REST server

The XiVO REST server implements POST and PUT methods for item creation and update respectively. Data is created using the POST method via a root URL and is updated using the PUT method via a root URL suffixed by /<id. The server expects to receive JSON encoded data. Only one item can be processed per request. The data format and required data fields are illustrated in the following example:

Request data format

{
   "id": "1",
   "prop1": "test"
}

When updating, only the id and updated properties are needed, omitted properties are not updated. Some properties can also be optional when creating an object.

Errors

A request to the web services may return an error. An error will always be associated to an HTTP error code, and eventually to one or more error messages. The following errors are common to all web services:

Error code Error message Description
406 empty Accept header missing or contains an unsupported content type
415 empty Content-Type header missing or contains an unsupported content type
500 list of errors An error occured on the server side; the content of the message depends of the type of errors which occured

The 400, 404 and 412 errors depend on the web service you are requesting. They are separately described for each of them.

The error messages are contained in a JSON list, even if there is only one error message:

[ message_1, message_2, ... ]