.. _embedded_swagger:

***********************************************************
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:

#. 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.json`` and 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
:ref:`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:

#. 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

#. Click the "Get Token" button
#. 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 :ref:`xivo-auth plugins <auth-stock-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".