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 via Swagger UI (what else?). Choose the xivo-auth service in the list of REST API. Under tokens, choose POST /tokens.

  1. In the top-right text box of the page (left to the “Explore” button), fill “token” with the string username:password where those credentials come from the Web Services Access you created earlier.

  2. Go back to the POST /tokens section and click on the yellow box to the right of the body parameter. This will pre-fill the body parameter.

  3. In the body parameter, set:

    • backend to xivo_service

    • expiration to the number of seconds for the token to be valid (e.g. 3600 for one hour). After the expiration time, you will need to re-authenticate to get a new token.

  4. Click “Try it out” at the end of the section

  5. In the response, you should see a token attribute.

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

Use the authentication token

To use the authentication token, choose the service for which you want to try the REST API, then paste the token in the top-right text box. You do not need to click “Explore” to apply the token change, the new token will be used automatically at the next request you send.

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