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
Last modified on : 07th Jul. 2025
This API relies on several dependencies, listed in the pom.xml file, which are installed and managed by Maven during the application compilation.
Dependencies required to build the application
Name |
Version |
Description |
|---|---|---|
|
Starter for building web, including RESTful, applications
using Spring MVC. Uses Tomcat as the default embedded
container.
|
|
|
Spring Data module for JPA repositories.
|
|
|
Library for communicating with the S3 Storage.
|
|
|
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.
|
|
|
A suite data-processing tools for Java.
|
|
|
Package that implements JSON encoders/decoders in Java.
|
|
|
Custom Java library with factorized code common between
microservices from the MetaboCloud project.
|
|
|
OpenAPI Generator generates API client libraries, server
stubs, documentation and configuration automatically,
given an OpenAPI Specification.
|
Dependencies required to test the application
Name |
Version |
Description |
|---|---|---|
|
Starter for testing Spring Boot applications with
libraries including JUnit Jupiter, Hamcrest and Mockito.
|
|
|
A Java DSL for synchronizing asynchronous operations.
|
Dependencies required to build the OpenAPI documentation
Name |
Version |
Description |
|---|---|---|
|
Java library that helps to automate the generation of API
documentation for spring boot projects.
|
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, Sphinx 8.1.3 is required with the following extension :
Name |
Version |
Description |
|---|---|---|
|
Sphinx extension for using the “Read the Docs” theme.
|
|
|
Sphinx extension for creating tabbed content when building HTML.
|
|
|
Sphinx extension for designing beautiful, screen-size responsive web-components.
|
Note
They can be installed using the following command :
$ pip install sphinx sphinx-rtd-theme sphinx-tabs sphinx-design
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
├── ci_settings.xml
├── doc
│ ├── class_doc.rst
│ ├── conf.py
│ ├── developers_guide.rst
│ ├── examples.rst
│ ├── index.rst
│ ├── overview.rst
│ ├── query_rest_api.rst
│ └── uml
│ ├── class_diagram.puml
│ ├── classes
│ │ ├── Config.puml
│ │ ├── Controllers.puml
│ │ ├── Exception.puml
│ │ ├── images
│ │ │ ├── Config.png
│ │ │ ├── Controllers.png
│ │ │ ├── Exception.png
│ │ │ ├── ImplementationBuilders.png
│ │ │ ├── ImplementationDirectors.png
│ │ │ ├── ImplementationFactories.png
│ │ │ ├── ImplementationReaders.png
│ │ │ ├── ImplementationServices.png
│ │ │ ├── ImplementationUtils.png
│ │ │ └── Models.png
│ │ ├── ImplementationBuilders.puml
│ │ ├── ImplementationDirectors.puml
│ │ ├── ImplementationFactories.puml
│ │ ├── ImplementationReaders.puml
│ │ ├── ImplementationServices.puml
│ │ ├── ImplementationUtils.puml
│ │ └── Models.puml
│ ├── dev
│ └── InDex_class_diagram.png
├── Dockerfile
├── LICENSE
├── pom.xml
├── README.md
├── src
│ ├── main
│ │ ├── java
│ │ │ └── fr
│ │ │ └── metabocloud
│ │ │ └── index
│ │ │ ├── Application.java
│ │ │ ├── config
│ │ │ │ └── S3Config.java
│ │ │ ├── controllers
│ │ │ │ ├── core
│ │ │ │ │ ├── AboutController.java
│ │ │ │ │ └── RootController.java
│ │ │ │ └── tool
│ │ │ │ └── CompoundsController.java
│ │ │ ├── exception
│ │ │ │ ├── FileNotFoundException.java
│ │ │ │ ├── GlobalExceptionHandler.java
│ │ │ │ ├── InteractionS3Exception.java
│ │ │ │ ├── InvalidCommunityException.java
│ │ │ │ ├── InvalidFormatException.java
│ │ │ │ ├── InvalidImageSizeException.java
│ │ │ │ └── InvalidOutputTypeException.java
│ │ │ ├── implementation
│ │ │ │ ├── builders
│ │ │ │ │ └── path
│ │ │ │ │ ├── ImagePathBuilder.java
│ │ │ │ │ ├── MolPathBuilder.java
│ │ │ │ │ ├── PathBuilder.java
│ │ │ │ │ └── PngPathBuilder.java
│ │ │ │ ├── directors
│ │ │ │ │ ├── PathDirector.java
│ │ │ │ │ └── SimplePathDirector.java
│ │ │ │ ├── factories
│ │ │ │ │ └── reader
│ │ │ │ │ ├── ReaderFactory.java
│ │ │ │ │ └── SimpleReaderFactory.java
│ │ │ │ ├── readers
│ │ │ │ │ ├── MolReader.java
│ │ │ │ │ ├── PngReader.java
│ │ │ │ │ └── Reader.java
│ │ │ │ ├── services
│ │ │ │ │ ├── CompoundsService.java
│ │ │ │ │ └── S3Service.java
│ │ │ │ └── utils
│ │ │ │ └── MetadataProcessor.java
│ │ │ └── models
│ │ │ └── enums
│ │ │ ├── Community.java
│ │ │ ├── Headers.java
│ │ │ ├── ImageSize.java
│ │ │ └── IndexErrorMessages.java
│ │ └── resources
│ │ ├── application-mesocentre.properties
│ │ ├── application-pfem.properties
│ │ ├── application.properties
│ │ ├── infos.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
│ │ │ │ └── OutputType.java
│ │ │ ├── providers
│ │ │ │ └── chebi
│ │ │ │ ├── MolProvider.java
│ │ │ │ └── PngProvider.java
│ │ │ └── stub
│ │ │ ├── chebi
│ │ │ │ ├── MolStub.java
│ │ │ │ └── PngStub.java
│ │ │ └── InchiKeyStub.java
│ │ ├── exception
│ │ │ └── FileNotFoundExceptionTest.java
│ │ └── implementation
│ │ ├── builders
│ │ │ └── PathBuilderTest.java
│ │ ├── CompoundsServiceTest.java
│ │ ├── directors
│ │ │ └── PathDirectorTest.java
│ │ ├── factories
│ │ │ └── reader
│ │ │ └── SimpleReaderFactoryTest.java
│ │ ├── readers
│ │ │ ├── MolReaderTest.java
│ │ │ ├── PngReaderTest.java
│ │ │ └── ReaderTest.java
│ │ ├── S3ServiceTest.java
│ └── utils
│ └── MetadataProcessorTest.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
- build_docker_image.sh
Script to build the Docker image in local.
- ci_settings.xml
CI/CD configuration.
docDirectory containing the source of the documentation/UML.
- Dockerfile
File used to build the Docker image of the application.
- LICENSE
Licence of the application.
- 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.
- README.md
README file giving an overview of the application.
src/main/java : Source code of the Application (see Classes documentation for more detail).
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.
static/: Folder containing the static files.
metabocloud-index.yaml : OpenAPI specification file describing the InDex REST API.
src/test/java : Source code of the unit tests.
src/test/resources : Resources necessary to run the tests.
compounds/: Folder containing the expected output files.