########
Overview
########

This project is based on `CDK « Chemistry Development Kit »`_, a set of open-source tools providing structural data to represent molecules, 
as well as methods to study these structures and perform calculations. 

  All three functionalities use the same kind of input which are an InChI, a plain text MOL, a MOL file, a SDF file.

However, this REST API only focuses on certain functionalities of this tool :

    1. The **calculation of some chemicals properties** such as : 

          * The raw formula, 
          * The monoisotopic and average masses, 
          * The canonical and stereochemical SMILES, 
          * The InChI and InChI key, 
          * The LogP.

    2. The **depiction** of a molecule in PNG or SVG format.
    3. The **conversion** of one molecular structure format into another (InChI, InChI Key, MOL, SDF).

All three functionalities use the same kind of input which are an ``InChI``, a ``plain text MOL``, a ``MOL file``, a ``SDF file``.

This REST API was developed in order to be use in a microservice architecture.

.. _CDK « Chemistry Development Kit »: https://github.com/cdk/cdk

!!!!

Prerequisites
=============

To run the application on your machine you must :

* Install the management tool `Maven`_. If you don't already have it, you can, on Linux, download it with the following command :

.. _Maven: https://maven.apache.org/

.. code-block:: console

    $ sudo apt install maven

!!!!

Installation
============

You can install this API by different ways.

Locally
-------

You can install the API on your machine to use it locally.  

First clone the git repository :

.. code-block:: console

    $ git clone https://git.mesocentre.uca.fr/unh-metabocloud/cdk-api.git

Move into the newly created folder ``cdk-api`` and launch the following command to compile the REST API into a JAR (.jar) :

.. code-block:: console

    $ cd cdk-api
    $ mvn -Dmaven.test.skip=true package

.. note:: 

    The option ``-Dmaven.test.skip=true`` enables to launch the application without running the unit tests.
    If you want to execute the tests, you just have to remove it or set the option to ``false``.

Then you can run the application from the newly created JAR :

.. code-block:: console

    $ java -jar target/metabocloud-cdk-api-2.9.0.jar

.. note::

    By default, the application is launched on port ``8081`` with the log level set to ``INFO``. But you can configure both parameters.

      * Use the option ``-Dserver.port`` to choose the port on which you want the application to listen :

        .. code-block:: console
            
            $ java -Dserver.port=8080 -jar target/metabocloud-cdk-api-2.9.0.jar

      * Use the option ``--debug`` to run the application in ``DEBUG`` level :

        .. code-block:: console

            $ java -jar target/metabocloud-cdk-api-2.9.0.jar --debug

      * You can of course use both options in the same time :

        .. code-block:: console

             $ java -Dserver.port=8080 -jar target/metabocloud-cdk-api-2.9.0.jar --debug

        *The application will then be launched in debug mode on the port 8080.*


With Docker
-----------

You can also launch the application by building a Docker image from the ``Dockerfile``. This method enables to build a container with the application 
and all the required dependencies in a single command.

First, clone the git repository :

.. code-block:: console

    $ git clone https://git.mesocentre.uca.fr/unh-metabocloud/cdk-api.git

Move into the repository and run the bash script ``build_docker_image.sh`` :

.. code-block:: console

    $ cd cdk-api
    $ ./build_docker_image.sh

You can now launched the application from the docker image :

.. code-block:: console

    $ docker run -p 8081:8081 cdk

.. note:: 
    You can also choose on which port you want the application to listen : 

    .. code-block:: console

        $ docker run -e DEBUG=true -p 8080:8081 cdk

    *This command will launched the application on the port 8080 in debug mode.*
    
!!!!

.. _web_usage:

Web usage
=========

You can use this application locally on your machine after installing it as explained in the section above, but you can also use it directly from the
`MetaboCloud Web Portal`_ by querying it at the following domain : ``https://metabocloud.mesocentre.uca.fr/cdk/``  

See the Swagger documentation below for details of the endpoints available.


.. _MetaboCloud Web Portal: https://metabocloud.mesocentre.uca.fr/


.. _doc_swagger:

!!!!

Documentation
=============

You can find information on the use of this REST API :

* Here on this documentation, for the generic information about the API and some examples of use.
* On the `Swagger documentation`_ for the information about the different endpoints available such as accepted requests, required parameters,
  possible responses, as well as examples.

.. _Swagger documentation: https://metabocloud.mesocentre.uca.fr/cdk/api/doc

!!!!

References
==========

1. Willighagen, E. L. et al. The Chemistry Development Kit (CDK) v2.0: atom typing, depiction, molecular formulas, and substructure searching. J Cheminform 9, 33 (2017). https://doi.org/10.1186/s13321-017-0220-4 
2. Steinbeck, C. et al. The Chemistry Development Kit (CDK):  An Open-Source Java Library for Chemo- and Bioinformatics. J. Chem. Inf. Comput. Sci. 43, 493–500 (2003). https://doi.org/10.1021/ci025584y