How to use the embedded REST API web interface (Swagger UI)

Every XiVO server embeds its own copy of the Swagger UI. The instance embedded in the XiVO allows you to directly try the requests with the in-page buttons.

For the rest of this article, we will consider that your XiVO is accessible under the hostname MY_XIVO.

The instance is available at: http://MY_XIVO/api

Before using the Swagger UI, there are a few prerequisites:

  • Accept the HTTPS certificate for each service of the XiVO

  • Add the permissions to use the REST API to a Web Services Access user

  • Obtain an authentication token

HTTPS certificates

For each service on the left menu that you want to try, you need to accept the HTTPS certificate for this service. To that end:

  1. click on the service in the menu on the left

  2. copy the URL you see in the text box at the top of the page, something like: https://MY_XIVO:9497/0.1/api/api.json and paste it in your browser

  3. accept the HTTPS certificate validation exception

  4. go back to http://MY_XIVO/api and select the service again (or click on the top-right “Explore” button)

You should now be able to see the different sections for the REST API of that service.

REST API permissions

You must create a Web Services Access with the right permissions before using the REST API. See Web Services Access.

Each endpoint has its own ACL, but you may add wildcard ACLs, like:

  • auth.# to gain access to all xivo-auth REST API endpoints

  • confd.# to gain access to all xivo-confd REST API endpoints

  • # to gain access to every endpoint of every service.

Warning

Only use wildcards when doing tests, not with a production REST API access. You should always restrict the permissions to the bare minimum.

Obtain an authentication token

You can get a token using the authentication form in the header of the Swagger UI:

  1. In the header of the page, fill in the authentication form with:

    • Username: the username from the Web Services Access you created earlier

    • Password: the password from the Web Services Access you created earlier

    • Backend: select xivo_service from the dropdown

  2. Click the “Get Token” button

  3. The token will be automatically retrieved and stored for use with all API requests

The token has a default expiration time. After the expiration time, you will need to re-authenticate to get a new token using the same form.

For more informations about the backends of xivo-auth, see xivo-auth plugins.

Use the authentication token

Once you have obtained a token using the authentication form in the header, it will be automatically used for all API requests.

You can now choose a REST API endpoint and “Try it out”.