How to query the API ?
======================

With cURL
---------

The REST API is queryable in command line by using ``cURL``

.. tabs::

    .. tab::

        .. tabs::

            .. tab:: File output

                **Command :**

                .. code-block:: console

                    $  curl --url 'https://metabocloud.mesocentre.uca.fr/...' \
                            --output <path/to/output/file>

                **Output :**

                The file is saved according to the path defined in the ``--output`` option.

            .. tab:: Console output

                **Command :**

                .. code-block:: console

                    $ curl -i --url 'https://metabocloud.mesocentre.uca.fr/...'

                **Output :**

                .. code-block:: console

                    Console output


With Python
-----------

One of the ways to query a REST-API with Python is to use the `requests`_ library.

.. _requests: https://fr.python-requests.org/en/latest/

After installing the ``requests`` library, you can query the REST-API with the following statements by ... :

.. code-block:: python

    import requests

    # Variables
    variable = "string"

    # Request
    result = requests.get(f"https://metabocloud.mesocentre.uca.fr/...")

    # Metadata
    headers = result.headers
    metadata = dict(filter(lambda x: x[0].startswith("X-Metadata"), headers.items()))

    # Output
    output = result.textdd

    print("Metadata : ", metadata)
    print("Resource :\n", output)

.. code-block::

    Output return

.. note::

    If you ran the application locally on your machine from a virtual environment or via Docker, you need to change the URL you send the 
    request to. This means that ``https://metabocloud.mesocentre.uca.fr/<microservice>/<endpoint>`` will become ``http://localhost:<default port>/<endpoint>``
    if you launched the application with the default parameters. 
    
    If you choose another port to run the application then you need to change the URL accordingly.


With a client generated by Swagger
----------------------------------

From the OpenAPI specification file describing this REST API, you can auto-generated a client in the language you want thanks to `Swagger`_
using the option ``Generate Client`` in the menu.

The OpenAPI specification file is downloadable here : https://metabocloud.mesocentre.uca.fr/<tool>/metabocloud-<tool>.yaml

.. _Swagger: https://editor.swagger.io/