.. _query_api:

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

With cURL
---------

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

.. tabs::

    .. tab::  With a string as input

        .. tabs:: 

            .. tab:: InChI 
                
                .. code-block:: console

                    curl --request POST \
                    --url https://metabocloud.mesocentre.uca.fr/cdk/<endpoint> \
                    --header 'Content-Type: multipart/form-data' \
                    --form 'inchi=<compound's InChI>'

            .. tab:: MOL in plain text

                .. code-block:: console

                    curl --request POST \
                    --url https://metabocloud.mesocentre.uca.fr/cdk/<endpoint> \
                    --header 'Content-Type: multipart/form-data' \
                    --form 'molText=<compound's MOL in plain text>'

    .. tab:: With a file as input

        .. tabs:: 

            .. tab:: MOL file 

                .. code-block:: console
                        
                    curl --request POST \
                    --url https://metabocloud.mesocentre.uca.fr/cdk/<endpoint> \
                    --header 'Content-Type: multipart/form-data' \
                    --form molFile=@<path of the MOL file>

            .. tab:: SDF file

                .. code-block:: console
                        
                    curl --request POST \
                    --url https://metabocloud.mesocentre.uca.fr/cdk/<endpoint> \
                    --header 'Content-Type: multipart/form-data' \
                    --form sdfFile=@<path of the SDF file>


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 :

.. tabs::

    .. tab:: With a string as input

        .. code-block:: python

            import requests

            inchi = "Compound's InChI"
            mol_text = None
            mol_file = None
            sdf_file = None

            multipart_form_data_input = {
                "inchi": (None, inchi),
                "molText": (None, mol_text),
                "molFile": (None, mol_file),
                "sdfFile": (None, sdf_file)
                }

            result = requests.post(f"https://metabocloud.mesocentre.uca.fr/cdk/<endpoint>", files=multipart_form_data_input)

            output = result.text
        
        .. note::

            The same applies to a plain text MOL input. However, the ``inchi`` variable becomes ``None`` and it is the ``mol_text`` variable which contains the data.

    .. tab:: With a file as input

        .. code-block:: python

            import requests

            inchi = None
            mol_text = None
            mol_file = None
            sdf_file = "path/to/file"

            multipart_form_data_input = {
                "inchi": (None, inchi),
                "molText": (None, mol_text),
                "molFile": (None, mol_file),
                "sdfFile": (sdf_file, open(sdf_file, 'rb'))
                }

            result = requests.post(f"https://metabocloud.mesocentre.uca.fr/cdk/<endpoint>", files=multipart_form_data_input)

            output = result.text

        .. note::

            The same applies to a MOL file input. However, the ``sdf_file`` variable becomes ``None`` and it is the ``mol_file`` variable which contains the path.
            Moreover, things change also in the ``multipart_form_data_input`` variable where the value of the key ``sdfFile`` must be change to ``(None, sdf_file)`` 
            and the value to the key ``molFile`` must be change to ``(mol_file, open(mol_file, 'rb'))``

.. caution:: 

    Only one type of input (InChI, MOL in plain text, MOL file or SDF file) can be send in one request. The other types of input must be set to ``None``

.. 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/cdk/metabocloud-cdk.yaml

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