Developer’s guide
This REST API was developed in Java 17 with the version 2.9.0 of the tool CDK.
Dependencies required
This API rests on several dependencies :
To build the application :
Spring Boot Starter Web 2.7.18 : Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container.
Spring Data JPA 2.7.18 : Spring Data module for JPA repositories.
CDK Bundle 2.9 : CDK tool
Lombok 1.18.30 : Java library that provides annotations to simplify Java development by automating the generation of boilerplate code. Used to the automatic generation of getters and setters methods.
Dozer 5.5.1 : Dozer is a Java Bean to Java Bean mapper that recursively copies data from one object to another.
Openapi Generator 7.2.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 2.7.18 : Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito.
Awaitility 4.2.0 : A Java DSL for synchronizing asynchronous operations
Mockito 4.5.1 : Java test framework
To build the documentation :
Springdoc 1.7.0 : Java library that helps to automate the generation of API documentation using spring boot projects.
- Sphinx 7.2.6Tool to build this documentation.
Sphinx-rtd-theme 1.3.0 : Sphinx extension to use the “Read the Docs” sphinx-rtd-theme/
Note
All theses dependencies, listed in the pom.xml file, are install and manage 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. InChIGenerationControllerTest)
Code organisation
The structure of the CDK REST API follows the Standard Directory layout created by Maven.
.
├── 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
│ │ │ └── cdk
│ │ │ ├── Application.java
│ │ │ ├── controllers
│ │ │ │ ├── cdk
│ │ │ │ │ ├── CdkConversionController.java
│ │ │ │ │ ├── CdkDepictionController.java
│ │ │ │ │ └── CdkPropertiesController.java
│ │ │ │ └── core
│ │ │ │ ├── AboutApiController.java
│ │ │ │ └── RootApiController.java
│ │ │ ├── exception
│ │ │ │ ├── GlobalExceptionHandler.java
│ │ │ │ ├── InvalidInputException.java
│ │ │ │ ├── InvalidParameterException.java
│ │ │ │ ├── RequestBodyException.java
│ │ │ │ └── StructurePropertiesException.java
│ │ │ ├── implementation
│ │ │ │ ├── CdkConversionImpl.java
│ │ │ │ ├── CdkDepictionImpl.java
│ │ │ │ ├── CdkPropertiesImpl.java
│ │ │ │ ├── ICdkReader.java
│ │ │ │ └── UtilsImpl.java
│ │ │ └── model
│ │ │ ├── AppInfos.java
│ │ │ ├── ErrorMessages.java
│ │ │ ├── FormatsEnum.java
│ │ │ └── HydrogenDisplayEnum.java
│ │ └── resources
│ │ ├── application-dev-mesocentre.properties
│ │ ├── application-dev-pfem.properties
│ │ ├── application-dev.properties
│ │ ├── conf.properties
│ │ ├── infos.properties
│ │ └── static
│ │ ├── about.yaml
│ │ └── metabocloud-cdk.yaml
│ └── test
│ ├── java
│ │ └── fr
│ │ └── metabocloud
│ │ └── cdk
│ │ ├── ApplicationTests.java
│ │ ├── controllers
│ │ │ ├── cdk
│ │ │ │ ├── ATestController.java
│ │ │ │ ├── CdkConversionControllerTest.java
│ │ │ │ ├── CdkDepictionControllerTest.java
│ │ │ │ ├── CdkPropertiesControllerTest.java
│ │ │ │ └── UtilsTestControllers.java
│ │ │ └── core
│ │ │ ├── AboutApiControllerTest.java
│ │ │ └── RootApiControllerTest.java
│ │ ├── data
│ │ │ ├── providers
│ │ │ │ ├── InchiKeysProvider.java
│ │ │ │ ├── InchiProvider.java
│ │ │ │ ├── MolFileProvider.java
│ │ │ │ ├── MolTextProvider.java
│ │ │ │ └── SdfProvider.java
│ │ │ └── stub
│ │ │ ├── InchiKeyStub.java
│ │ │ ├── InchiStub.java
│ │ │ ├── MolStub.java
│ │ │ └── SdfStub.java
│ │ ├── implementation
│ │ │ ├── CdkConversionImplTest.java
│ │ │ ├── CdkDepictionImplTest.java
│ │ │ ├── CdkPropertiesImplTest.java
│ │ │ └── ICdkReaderTest.java
│ │ ├── model
│ │ │ └── AppInfosTest.java
│ │ └── OpenApiCoreIntegrationTest.java
│ └── resources
│ ├── confTest.properties
│ ├── conversion
│ │ ├── CaffeineFromInChI.mol
│ │ ├── CaffeineFromInChI.sdf
│ │ ├── CaffeineFromMOL.sdf
│ │ ├── CaffeineFromMOL_SDF.mol
│ │ └── CaffeineFromSDF.sdf
│ ├── depiction
│ │ ├── Caffeine_InChI_Default.png
│ │ ├── Caffeine_InChI_Default.svg
│ │ ├── Caffeine_InChI_Minimal.png
│ │ ├── Caffeine_InChI_Minimal.svg
│ │ ├── Caffeine_InChI_NonChiral.png
│ │ ├── Caffeine_InChI_NonChiral.svg
│ │ ├── Caffeine_MOL_SDF_Default.png
│ │ ├── Caffeine_MOL_SDF_Default.svg
│ │ ├── Caffeine_MOL_SDF_Minimal.png
│ │ ├── Caffeine_MOL_SDF_Minimal.svg
│ │ ├── Caffeine_MOL_SDF_NonChiral.png
│ │ └── Caffeine_MOL_SDF_NonChiral.svg
│ └── input
│ ├── Caffeine
│ │ ├── Caffeine.mol
│ │ └── Caffeine.sdf
│ ├── CaffeineInvalid.mol
│ ├── CaffeineInvalid.sdf
│ ├── Cholesterol
│ │ ├── Cholesterol.mol
│ │ └── Cholesterol.sdf
│ ├── D-Glucose
│ │ ├── D-Glucose.mol
│ │ └── D-Glucose.sdf
│ ├── MethylTryptophan
│ │ ├── MethylTryptophan.mol
│ │ └── MethylTryptophan.sdf
│ ├── Sphinganine1Phosphate
│ │ ├── Sphinganine1Phosphate.mol
│ │ └── Sphinganine1Phosphate.sdf
│ └── VitaminE
│ ├── VitaminE.mol
│ └── VitaminE.sdf
docDirectory containing the source of the documentation
pom.xmlXML 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/javaSource code of the Application- fr.metabocloud.cdk :
Application.java : Enables to run the application using the Web framework SpringBoot.
- fr.metabocloud.cdk.controllers.cdkPackage containing controllers associated to the tool CDK
CDKConverterController.java : Controller for the endpoint “/convert” to the conversion of a format into another
CDKDepictionController.java : Controller for the endpoint “/depict” to the depiction of a molecule
CDKPropertiesController.java : Controller for the endpoint “/properties” to compute chemical properties
- fr.metabocloud.cdk.controllers.corePackage containing controllers associated to the REST API
AboutApiController.java : Controller for the endpoint “/about” to retrieve the metadata associated to the REST API
RootApiController : Controller for the root “/” of the REST API
- fr.metabocloud.cdk.exceptionPackage managing the exceptions that can be thrown by the REST API
GlobalExceptionHandler.java : Global handler which manage exceptions for all controllers
InvalidInputException.java : Exception thrown when an invalid input is sent in the request
InvalidParameterException.java : Exception thrown when an invalid parameter is sent in the request
RequestBodyException.java : Exception thrown when the structure of the request body is incorrect
StructurePropertiesException.java : Exception thrown when the structure of the “properties” field is incorrect
- fr.metabocloud.cdk.implementationPackage containing classes which implement methods to process the received requests
CdkConvertionImpl.java : Implementation for the endpoint “/convert”
CdkDepictionImpl.java : Implementation for the endpoint “/depict”
CdkPropertiesImpl.java: Implementation for the endpoint “/properties”
ICdkReader.java : Process input so that it can be used by CDK
UtilsImpl.java : Utils class to help process the request sent in the controllers
- fr.metabocloud.cdk.modelPackage containing model objects
AppInfos.java : Model for the metadata related to the REST API
ErrorMessages.java : Enum for each error messages
FormatsEnum.java : Enum for each accepted formats
HydrogenDisplayEnum.java : Enum for each accepted argument for the parameter “hydrogenDisplay”
src/main/resources :Resources associated to the application*.properties : Configuration files of the application properties
static/Folder containing the static filesabout.yaml : OpenAPI file describing metadata of the REST API
metabocloud-cdk.yaml : Main OpenAPI file describing the CDK REST API
src/test/javaContain the Java sources of the unit tests- fr.metabocloud.cdk :
ApplicationTests.java : Test on the main application
- fr.metabocloud.cdk.controllers.cdkPackage containing tests on controllers associated to the tool CDK
CDKConverterControllerTest.java : Tests on the controller for the endpoint “/convert”
CDKDepictionControllerTest.java : Tests on the controller for the endpoint “/depict”
CDKPropertiesControllerTest.java: Tests on the controller for the endpoint “/properties”
- fr.metabocloud.cdk.controllers.corePackage containing tests on controllers associated to the REST API
AboutApiControllerTest.java : Tests on the controller for the endpoint “/about” to retrieve the metadata associated to the REST API
RootApiControllerTest : Tests on the controller for the root “/” of the REST API
- fr.metabocloud.cdk.data.providersPackage containing the providers used to import data into tests
InchiKeysProvider.java : Provider of InChI Key
InchiProvider.java : Provider of InChI
MolFileProvider.java : Provider of MOL in file
MolTextProvider.java : Provider of MOL in plain text
SdfProvider.java : Provider of SDF in file
- fr.metabocloud.cdk.data.stubPackage containing classes which store the input to used in tests
InchiKeyStub.java : Store InChI Keys of several compounds
InchiStub.java : Store InChIs of several compounds
MolStub.java : Store MOLs of several compounds
SdfStub.java : Store SDFs of several compounds
- fr.metabocloud.cdk.implementation: Package containing tests on the implemented methods to process the received requests
CdkConvertionImplTest.java : Tests on the implementation for the endpoint “/convert”
CdkDepictionImplTest.java : Tests on the implementation for the endpoint “/depict”
CdkPropertiesImplTest.java: Tests on the implementation for the endpoint “/properties”
ICdkReaderTest.java : Tests on the input processing which can be used by CDK
UtilsImplTest.java : Tests on the utils class helping process the request sent in the controllers
- fr.metabocloud.cdk.model: Package containing tests on the model object
AppInfosTest.java : Tests on the model of the metadata
src/test/resourcesHost the files that are not Java sources but are necessary to run the tests.conversion/: Folder containing result for the different type of conversion for the caffeinedepiction/: Folder containing result for the different type of depiction for the caffeineinput/: Folder containing the input used to run the tests
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.