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
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
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:
- click on the service in the menu on the left
- 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.jsonand paste it in your browser
- accept the HTTPS certificate validation exception
- 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-authREST API endpoints
confd.#to gain access to all
xivo-confdREST API endpoints
#to gain access to every endpoint of every service.
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
in the list of REST API. Under
- In the top-right text box of the page (left to the “Explore” button), fill “token” with the
username:passwordwhere those credentials come from the Web Services Access you created earlier.
- Go back to the
POST /tokenssection and click on the yellow box to the right of the
bodyparameter. This will pre-fill the
- In the
expirationto 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.
- Click “Try it out” at the end of the section
- In the response, you should see a
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”.