Overview

User Guide > Overview

The Xelion API is a RESTful interface. It is stateless and relies on the HTTP protocol. Each resource is identified by a unique URL and is accessible through HTTP requests.
The access to most resources is restricted which means that users must be authenticated in order to retrieve them.

Resources

Base URL

The API base URL on a Xelion server has the form of:

https://<host-name>/api/<version>/<tenant>/

For example:

https://www.xelion.nl/api/v1/master/
Tenants

The API URLs contain the tenant name. The master tenant is referenced by the name master. The name master represents the tenant name in a single tenant system as well.

Resource structure

The resources are organized in a tree structure according to their types. For instance, communication resources (email messages, call-logs, etc.) are found under:

https://<base-url>/communications                      -- communication items
https://<base-url>/communications/1234                 -- the communication item '1234'
https://<base-url>/communications/1234/audio           -- the audio recording of the item
...

And wallboards items are retrieved from:

https://<base-url>/wallboards                         -- wallboards
https://<base-url>/wallboards/1234                    -- the wallboard '1234'
https://<base-url>/wallboards/1234/agent              -- the agents of the wallboard
https://<base-url>/wallboards/1234/agent/5678         -- the wallboard agent '5678'
...

Accessing Resources

Resources may be created, changed, retrieved and removed. Some resources offers only a subset of these operations. Secured resources are available to administrators only.

The HTTP methods the interface accepts are related to the resource operations in the following way.

HTTP method description safety1 idempotency2

PUT

Replace or update a resource

Unsafe

idempotent

DELETE

Delete a resource

Unsafe

idempotent

GET

Retrieve a resource

Safe

nullipotent

POST

Create, process data, trigger action

Unsafe

non-idempotent

PATCH

Update a resource (partially)

Unsafe

idempotent

1) safe: doesn’t effect other operations. unsafe: can modify the data set.
2) idempotent: after first execution, subsequent operations with identical input will not change the data set. non-idempotent: each operation modifies the data, e.g. create a new resource. nullipotent: the operation has no side effect.

Examples of requests
GET    https://../me/favorites          -- retrieve user's favorites
PUT    https://../me/favorites/1234     -- add object 1234 to user's favorites
DELETE https://../me/favorites/1234     -- remove object 1234 from user's favorites
PUT    https://../me/message            -- set user's message
POST   https://../communications/sms    -- send an SMS message
POST   https://../addressables/1234     -- add the object 1234 to the data set
PATCH  https://../me/phone/settings     -- update user's phone settings

Note that the PUT methods above do not create a new object and will not alter the data set when applied repeatedly.

Request parametrization

Numerous requests accept parameters that effect the request’s results. These parameters are passed to the server in the query part of the URL.

Examples of request parameters
GET    https://../commnication?limit=10
GET    https://../addressables?name=arnon&order_by=mru

The limit parameter in the first request, for example, orders the server to return 10 objects at most.
The name parameter in the second request select objects that match name 'arnon'.

String matching

The name parameter performs a start-with matching and it supports wildcards. The wildcard character is an asterisk (*).

For example, considering the data set:

  • Jan Janssen

  • Jan de Jong

  • Bert Janssen

string matching give the next results:

Jan J

→     [ Jan Janssen ]
Jan*J

→     [ Jan Janssen, Jan de Jong ]
*Janssen

→     [ Jan Janssen, Bert Janssen ]
Jan

→     [ Jan Janssen, Jan de Jong, Bert Janssen ]
de

→     [ ]

Ordering results and Paging

If the data set is naturally ordered (by object ID or date) then the server, unless otherwise instructed, returns the objects in that order. Pagination of the results is supported when the result set is naturally ordered. When the data set is not ordered or when the parameter order_by=mru is specified, the server returns the most recently used objects (MRU).

Pagination is cursor based. The parameters before and after request results before or after the specified ID respectively. For example:

GET    https://../addressables?after=1234

A server response with pagination information include links to the next and previous pages.

{
    "data" : [
        {
            "object" : {
                /* ... */
            },
        },
        {
            ...
        },
...
    ],
    "meta" : {
       "links": [
            {
              "rel": "refresh",
              "href": "http://.../api/v1/master/addressables",
              "method": "GET"
            },
            {
              "rel": "next",
              "href": "http://.../api/v1/master/addressables?after=2345",
              "method": "GET"
            },
            {
              "rel": "previous",
              "href": "http://.../api/v1/master/communications?before=1234",
              "method": "GET"
            }
        ],
        "paging" : {
            "previousId" : 1234,
            "nextId" : 2345,
        }
    }
}

Response codes

As a response for a request the API returns one of the following HTTP codes.

HTTP Status Description

200 OK

The request is successfully processed

400 Bad Request

Invalid request: incomplete, malformed or other client error

401 Unauthorized

The client is not logged in

403 Forbidden

The client is not authorized to access the resource

404 Not found

The resource is not found

500 Internal Server Error

Internal server error occurred

An error response includes a textual description, an internal error code and possibly a link to extra information.

{
    "errorCode": "10004",
    "message": "Wrong user name or password",
    "info" : "resource /me/login"
}

The error codes list describes the errors, and can be used for presenting a locaized and friendly error message for the user.

Resource Hierarchy

The resources are organized in a type hierarchy. The toplevel resource is the most general type. The further down in the hierarchy a resource is specified, the more specific it is.

Example of subtree in the the resource hierarchy
/addressables                       -- all addressables
/addressables/1234                  -- the addressable object with ID 1234
/addressables/1234/addresses        -- the addresses of the addressable 1234
/addressables/1234/addresses/5678   -- the address with ID 5678 of the addressable 1234
Table 1. The resource hierarchy and the semantics of the HTTP requests
Resource type GET DELETE PUT POST PATCH

Top level type or collection type, e.g. /chats

Search chat sessions. Optionally with query options.

N/A

N/A

Create a new object of parent’s type, e.g. a chat session

N/A

An object, e.g. /addressables/1234

Return object’s attributes

Remove the object

Replace object’s attributes

N/A

Update some object’s attributes

Action like resource, e.g. /me/register

Optionally: return status, e.g. registration status

N/A

N/A

Execute an action, e.g. register phone with server

N/A
User resources

As a rule, different users share the same view of the resources. For example:

https://.../addressables/1234

is the same addressable for all users.
That rule holds for all resources, except for the resources under the toplevel resource me. These resources are handled in the context of the user that query them.

Examples
https://.../me/status          -- set/get the user's status
https://.../me/favorites       -- the user's favorites list

Resource Data

Resource data is transferred in JSON format. A client request that contains payload must set the media type explicitly with content-type header:

Content-Type: application/json

The character encoding is assumed to be utf-8.

Data model

Server replies contain one of the following data types:

  • scalar data types, e.g. text string or number

  • Xelion objects

  • a container type that holds one or more scalars and/or Xelion objects.

Examples

A read request of a resource returns both the object data and meta information of that resource. Here is a simplified example of a retrieval of an object from the favorites list.

Request
GET    https://xelion.nl/api/v1/master/me/favorites/1234
Response body
{
  "object": {
    "commonName": "Arnon Ron",
    "addressable": {
      "commonName": "Arnon Ron",
      "oid": "16180339",
      "objectType": "Person",
    },
    "organisation": {
       ...
    },
    ...
    "isUser": true
  },
  "links": [
    {
      "rel": "self",
      "href": "http://xelion.nl/api/v1/master/addressables/16180339",
      "method": "GET"
    },
    {
      "rel": "remove",
      "href": "http://xelion.nl/api/v1/master/me/favorites/16180339",
      "method": "DELETE"
    }
  ]
}

In the example above the meta data consists of a list of links. The first link is the favorite object’s resource id and the second link is the url that removes this favorite from the list.

The next example demonstrates a search of addressables by the string 'ron'.

Request
GET    https://xelion.nl/api/v1/master/addressables?name=ron
Response body
{
  "data": [
    {
      "object": {
        "commonName": "Ron Enterprises",
        "oid": "1567406",
        "objectType": "Organisation",
      },
      "links": [
        {
          "rel": "self",
          "href": "http://xelion.nl/api/v1/master/addressables/1567406",
          "method": "GET"
        }
      ]
    },
    {
      "object": {
          ...
      },
      "links": [
        {
          ...
        }
      ]
    },
    ...
    {
      "object": {
        "commonName": "Arnon Ron",
        "oid": "1556377",
        "objectType": "Person",
      },
      "links": [
        {
          "rel": "self",
          "href": "http://xelion.nl/api/v1/master/addressables/1556377",
          "method": "GET"
        }
      ]
    }
  ],
  "meta": {
    "links": [{
      "refresh": {
        "rel": "refresh",
        "href": "http://xelion.nl/api/v1/master/addressables?name=arnon",
        "method": "GET"
      },
      "previous": {
        "rel": "previous",
        "href": "http://xelion.nl/api/v1/master/addressables?name=arnon&before=1556377",
        "method": "GET"
      },
      "next": {
        "rel": "next",
        "href": "http://xelion.nl/api/v1/master/addressables?name=arnon&after=1567406",
        "method": "GET"
      }],
      "paging" : {
        "previousId": "1556377",
        "nextId": "1567406",
      }
    }
  }
}

The request asks for addressables that match the text string 'ron'. The response consists of two structures: a list of objects and meta data of the response. The meta data has paging information with links for refreshing the current page and retrieving the previous and the next pages.

Sessions and permissions

A session is created by a login request and is ended by a logout request. A successful login request starts a new session and returns the session token (max 512 characters). The client adds the session token to the authorization header of the requests.

Authorization: xelion <authorization-token>

The session token remains valid until it is expired or revoked. The token’s expiration date is included in the Login response. The client app must then renew the token by invoking renew or by logging in again to the server.

Clients may need to logout to switch user or on removal of the client app.

Access to most resources is restricted to users with a session. Some secured resources are available to administrators only.
The resource access permission is one of the following.

Table 2. Permissions
Permission Description

Guest

The request requires no session associated with it

User

The request must be associated with a session

Administrator

The request must be associated with a session of an Xelion Administrator of a tenant.

Master

The request must be associated with a session of an Xelion Administrator of the master tenant.

Compression of http response data

The body of an http response can be compressed with gzip. This is usefull when working with slow network connections.
If you want the data to be compressed you have add the following header to your request:

Accept-Encoding: gzip

If the reponse body is compressed then the response will include the header:

Content-Encoding: gzip

If the reponse contents cannot be compressed, that will be the case for example with images and audio files, then no compression will take place and the Content-Encoding header will not be added.

Session Concurrency Limits

Xelion limits the number of concurrent requests a session can have. These restrictions aim to prevent the server from being flooded by requests from one client. Two session limits are forced by the server:

  • maximum of 10 concurrent requests

  • maximum of 30 seconds for a request to start processing (in case a request waits on busy resources)

When one of these two restrictions is violated the request will be rejected with HTTP code 429 (Too Many Requests).