Developer’s guide
This REST API was developed in Java 17 from scratch, meaning that it is not based on a pre-existing tool. It enables the retrieval of molecule structure/representation files from a custom S3 storage containing data coming from different communities.
Dependencies required
This API relies on several dependencies :
To build the application :
Spring Boot Starter Web
3.3.3: Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container.Spring Data JPA
3.3.3: Spring Data module for JPA repositories.AWS SDK For Java
2.28.2: Library for communicating with the S3 Storage.Lombok
>=1.18.34: Java library that provides annotations to simplify Java development by automating the generation of boilerplate code. Used for the automatic generation of getters and setters methods.JSON
20240303: Package that implements JSON encoders/decoders in Java.Microservice Core Lib
1.0.1: Custom Java library with factorized code common between microservices from the MetaboCloud project.Openapi Generator
7.8.0: OpenAPI Generator allows generation of API client libraries, server stubs, documentation and configuration automatically, given an OpenAPI Specification.Jackson Databind Nullable
0.2.6: JsonNullable wrapper class and Jackson module to support fields with meaningful null values.
To test the application :
Spring Boot Starter Test
3.3.3: Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito.Awaitility
>=4.2.2: A Java DSL for synchronizing asynchronous operations
To build the documentation :
Springdoc
2.6.0: Java library that helps to automate the generation of API documentation for spring boot projects.
Note
All theses dependencies, listed in the pom.xml file, are installed and managed by Maven during the application compilation.
Unit and functional testing
Unit and functional tests are in the src/test/java directory. To run all tests, use the following command :
$ mvn test
Note
You can launch specific tests by using the argument -Dtest.
$ mvn test -Dtest=<name of the file>
Where <name of the file> is the file containing the tests you want to run without its extension (e.g. CompoundsControllerTest)
Documentation generation
To generate the ReadTheDocs documentation, the following tool is required :
Sphinx
7.4.7: Tool to build the ReadTheDocs documentation.Sphinx-rtd-theme
2.0.0: Sphinx extension to use the “Read the Docs” theme.Sphinx Tabs
3.4.5: Sphinx extension to create tabbed content when building HTML.
Note
They can be installed using the following command :
$ pip install sphinx sphinx-rtd-theme sphinx-tabs
Then, once Sphinx and its extensions are installed, the documentation can be generated by using the following command :
$ sphinx-build -M html doc build
The documentation is then generated in HTML and can be accessed from the build/html folder.
S3 Storage organisation
The InDex REST API is associated with a S3 Storage containing all the files than can be retrieved. The S3 Storage is hosted by the Clermont Auvergne Mesocentre.
Currently, this S3 Storage contains files coming only from one community chebi.
Two types of files are available :
PNG imagesof molecules in three different sizes (50 x 50 px corresponding tosmall, 350 x 350 px corresponding tomediumand 700 X 700 px corresponding tolarge)MOL filesof molecules
The architecture of the S3 Storage then contains several layers :
First layer - Format of the file :
pngandmolSecond layer - Origin of the image : the community from which the files come (e.g.
chebi)Third layer - Size of the image : three categories which are
small(50 x 50 px),medium(350 x 350 px) andlarge(700 x 700 px) => only forpngformat- Fourth layer - File name :
PNG image are named from the
InChI Keyof the molecule, theimage sizeand theimage format(e.g. AFENDNXGAFYKQO-UHFFFAOYSA-N_50.png, YNPGYMZVNLIZLD-BQFKTQOQSA-N_350.png, KMTDMTZBNYGUNX-UHFFFAOYSA-N_700.png)MOL file are named from the
InChI Keyof the molecule, and thefile format(e.g. AFENDNXGAFYKQO-UHFFFAOYSA-N.mol, YNPGYMZVNLIZLD-BQFKTQOQSA-N.mol, KMTDMTZBNYGUNX-UHFFFAOYSA-N.mol)
Structure of the S3 Storage : (The list of files is just an example and is of course non-exhaustive)
.
├── png
│ └── chebi
│ ├── large
│ │ ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_700.png
│ │ ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_700.png
│ │ └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_700.png
│ ├── medium
│ │ ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_350.png
│ │ ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_350.png
│ │ └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_350.png
│ └── small
│ ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_50.png
│ ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_50.png
│ └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_50.png
└── mol
└── chebi
├── AFENDNXGAFYKQO-UHFFFAOYSA-N.mol
├── KMTDMTZBNYGUNX-UHFFFAOYSA-N.mol
└── YNPGYMZVNLIZLD-BQFKTQOQSA-N.mol
Code organisation
The structure of the InDex REST API follows the Standard Directory layout created by Maven.
.
├── build_docker_image.sh
├── doc # Folder with the source of the documentation
├── Dockerfile
├── LICENSE
├── Makefile
├── pom.xml
├── README.md
└── src # Folder with the code source of the application
├── main
│ ├── java
│ │ └── fr
│ │ └── metabocloud
│ │ └── index
│ │ ├── Application.java
│ │ ├── config
│ │ │ └── S3Config.java
│ │ ├── controllers
│ │ │ ├── core
│ │ │ │ ├── AboutController.java
│ │ │ │ └── RootController.java
│ │ │ └── tool
│ │ │ └── CompoundsController.java
│ │ ├── exception
│ │ │ ├── FileNotFoundException.java
│ │ │ └── GlobalExceptionHandler.java
│ │ ├── implementation
│ │ │ ├── builders
│ │ │ │ ├── ImagePathBuilder.java
│ │ │ │ ├── MolPathBuilder.java
│ │ │ │ ├── PathBuilder.java
│ │ │ │ └── PngPathBuilder.java
│ │ │ ├── CompoundsImpl.java
│ │ │ ├── directors
│ │ │ │ ├── PathDirector.java
│ │ │ │ └── SimplePathDirector.java
│ │ │ ├── readers
│ │ │ │ ├── MolReader.java
│ │ │ │ ├── PngReader.java
│ │ │ │ └── Reader.java
│ │ │ └── S3Service.java
│ │ └── models
│ │ ├── Community.java
│ │ ├── Headers.java
│ │ ├── ImageSize.java
│ │ ├── IndexErrorMessages.java
│ │ └── OutputType.java
│ └── resources
│ ├── application-mesocentre.properties
│ ├── application-pfem.properties
│ ├── application.properties
│ ├── conf.properties
│ ├── infos.properties
│ ├── s3storage.properties
│ └── static
│ └── metabocloud-index.yaml
└── test
├── java
│ └── fr
│ └── metabocloud
│ └── index
│ ├── ApplicationTests.java
│ ├── controllers
│ │ ├── core
│ │ │ ├── AboutControllerTest.java
│ │ │ └── RootControllerTest.java
│ │ └── tool
│ │ └── CompoundsControllerTest.java
│ ├── data
│ │ ├── models
│ │ │ └── Constants.java
│ │ ├── providers
│ │ │ └── chebi
│ │ │ ├── MolProvider.java
│ │ │ └── PngProvider.java
│ │ └── stub
│ │ ├── chebi
│ │ │ ├── MolStub.java
│ │ │ └── PngStub.java
│ │ └── InchiKeyStub.java
│ ├── exception
│ │ └── FileNotFoundExceptionTest.java
│ └── implementation
│ ├── builders
│ │ └── PathBuilderTest.java
│ ├── CompoundsImplTest.java
│ ├── directors
│ │ └── PathDirectorTest.java
│ ├── readers
│ │ ├── MolReaderTest.java
│ │ ├── PngReaderTest.java
│ │ └── ReaderTest.java
│ └── S3ServiceTest.java
└── resources
├── compounds
│ ├── mol
│ │ └── chebi
│ │ ├── Caffeine.mol
│ │ ├── Caffeine_without_metadata.mol
│ │ ├── Cholesterol.mol
│ │ ├── Cholesterol_without_metadata.mol
│ │ ├── D-Glucose.mol
│ │ ├── Sphinganine1Phosphate.mol
│ │ └── VitaminE.mol
│ └── png
│ └── chebi
│ ├── large
│ │ ├── Caffeine.png
│ │ ├── Cholesterol.png
│ │ ├── D-Glucose.png
│ │ ├── Sphinganine1Phosphate.png
│ │ └── VitaminE.png
│ ├── medium
│ │ ├── Caffeine.png
│ │ ├── Cholesterol.png
│ │ ├── D-Glucose.png
│ │ ├── Sphinganine1Phosphate.png
│ │ └── VitaminE.png
│ └── small
│ ├── Caffeine.png
│ ├── Cholesterol.png
│ ├── D-Glucose.png
│ ├── Sphinganine1Phosphate.png
│ └── VitaminE.png
└── confTest.properties
- build_docker_image.sh
Script to build the Docker image in local
docDirectory containing the source of the documentation
- pom.xml
XML File at the root of the repository that contains information about the project, configuration details and dependencies needed, used by Maven to build the project.
src/main/java : Source code of the Application
fr.metabocloud.index :
Application.java : Enables to run the application using the Web framework SpringBoot.
fr.metabocloud.index.controllers.config : Package containing configuration classes
S3Config : Configure the S3 Storage.
fr.metabocloud.index.controllers.core : Package containing controllers associated to the REST API metadata
AboutController.java : Controller for the endpoint “/about” to retrieve the metadata associated to the REST API.
RootController : Controller for the root “/” of the REST API.
fr.metabocloud.index.controllers.tool : Package containing controllers associated to the tool itself
CompoundsController.java : Controller for the endpoint “/compounds/{inchiKey}.{format}” which retrieve molecule structure/representation files from a custom S3 storage containing data coming from different communities.
fr.metabocloud.index.exception : Package managing exceptions that can be thrown by the REST API
FileNotFoundException.java : Exception thrown when a file is not found in the S3 Storage.
GlobalExceptionHandler.java : Global handler which manages exceptions for all controllers.
fr.metabocloud.index.implementation : Package containing classes which implement methods to process the received requests
CompoundsImpl.java : Implementation for the endpoint “/compounds/{inchiKey}.{format}”.
S3Service.java : Service to communicate with the S3 Storage.
fr.metabocloud.index.implementation.builders : Package regrouping classes builders
ImagePathBuilder.java : Abstract sub-class of PathBuilder representing a image path builder which builds the path of an image after checking the validity of the required attributes.
MolPathBuilder.java : Sub-class of ImagePathBuilder representing a MOL path builder which builds a path for MOL files.
PathBuilder.java : Abstract parent class that enables the construction of a file path after validating the required attributes.
PngPathBuilder.java : Sub-class of ImagePathBuilder representing a PNG path builder which builds a path for PNG images.
fr.metabocloud.index.implementation.directors : Package regrouping classes directors
PathDirector.java : Interface for a director that builds paths for retrieving files.
SimplePathDirector.java : Sub-class of PathDirector which implements a director building paths for MOL and PNG files.
fr.metabocloud.index.implementation.readers : Package regrouping classes readers
MolReader.java : Sub-class of Reader which retrieves a MOL file and extract its metadata.
PngReader.java : Sub-class of Reader which retrieves a PNG image and extract its metadata.
Reader.java : Abstract parent class which retrieves a file and extract its metadata.
fr.metabocloud.index.models : Package containing models
Community.java : Enumeration representing the different communities available for retrieving data.
Headers.java : Enumeration representing the various HTTP header keys and values used in the application.
ImageSize.java : Enumeration representing the available image sizes for the PNG images.
IndexErrorMessages.java : Enumeration representing specific error messages that may be returned by the application.
OutputType.java : Enumeration representing the types of output that can be requested by the application.
src/main/resources : Resources associated to the application
application-mesocentre.properties : Configuration file of the application with the properties required to run it on the MetaboCloud production.
application-pfem.properties : Configuration file of the application with the properties required to run it on the PFEM dev server.
application.properties : Configuration file of the application with the properties required to run it in local.
infos.properties : Configuration file containing the metadata associated to the REST API.
s3storage.properties : Configuration file containing the properties required to set up the S3 Storage.
static/: Folder containing the static files
metabocloud-index.yaml : OpenAPI specification file describing the InDex REST API.
src/test/java : Contain the Java sources of the unit tests
fr.metabocloud.index :
ApplicationTests.java : Test on the main application
fr.metabocloud.index.controllers.core : Package containing tests on controllers associated to the REST API metadata
AboutControllerTest.java : Tests on the controller for the endpoint “/about” to retrieve the metadata associated to the REST API.
RootControllerTest : Tests on the controller for the root “/” of the REST API.
fr.metabocloud.index.controllers.index : Package containing tests on controllers associated to the tool itself
CompoundsControllerTest.java : Tests on the controller for the endpoint “/compounds/{inchiKey}.{format}”.
fr.metabocloud.index.data.models : Package containing models used for tests
Constants.java : Model with all constants used in the different tests.
fr.metabocloud.index.data.providers.chebi : Package containing the providers used to import data coming from ChEBI into tests
MolProvider.java : Provider specific for MOL files.
PngProvider.java : Provider specific for PNG images.
fr.metabocloud.index.data.stub : Package containing classes which store the common input between all communities used in tests
InchiKeyStub.java : Store InChI Keys of compounds.
fr.metabocloud.index.data.stub.chebi : Package containing classes which store the input coming from ChEBI used in tests
MolStub.java : Store data required to test for MOL files retrieval.
PngStub.java : Store data required to test for PNG images retrieval.
fr.metabocloud.index.exception: Package containing tests on the custom exceptions that can be thrown by the REST API
FileNotFoundExceptionTest.java : Tests on the FileNotFound custom exception.
fr.metabocloud.index.implementation: Package containing tests on implemented methods to process the received requests
CompoundsImplTest.java : Tests on the implementation for the endpoint “/compounds/{inchiKey}.{format}”.
S3ServiceTest.java : Tests on the service used to communicate with the S3 Storage.
fr.metabocloud.index.implementation.builders: Package containing tests on the builder classes
PathBuilderTest.java : Tests on all the PathBuilder classes.
fr.metabocloud.index.implementation.directors: Package containing tests on the director classes
PathDirectorTest.java : Tests on all the PathDirector classes.
fr.metabocloud.index.implementation.readers: Package containing tests on the reader classes
MolReaderTest.java : Tests on the MolReader class.
PngReaderTest.java : Tests on the PngReader class.
ReaderTest.java : Tests on all the Reader classes.
src/test/resources : Host the files that are not Java sources but are necessary to run the tests.
compounds/: Folder containing the expected output files
Note
A Controller is a class that implements operations defined by the API. It will receive the request, process it and send back the response.
Note
The highlight is a source folder, the italic a package, and the bold a file.
