Developer’s guide

This API-REST was developed with python 3.10.12 with the version 2.1.5 of pygoslin, the Python implementation of the Goslin tool.

Dependencies

Last modified on : 14th Apr. 2025

This API relies on several dependencies which must be installed in the application environment (venv, Docker, …) for the application to work.

Note

All theses dependencies are listed in the requirements.txt file and can be install at once with the command :

$ pip install -r requirements.txt

Dependencies required to use the application

Name

Version

Description

Pygoslin

2.1.5
The Python implementation of the Goslin Tool.

Loguru

0.7.3
Package for implementing logging.

OpenAPI Generator CLI

7.12.0
Tool to generates API client libraries and server source code
(such as model objects) automatically, from an OpenAPI
Specification.

Pandas

2.2.3
Package that provides fast, flexible, and expressive data
structures designed.

Python Dotenv

1.1.0
Package to read key-value pairs from a .env file and can set
them as environment variables.

PyYAML

2.8.1
YAML parser and emitter for Python.

Requests

2.32.3
Package for sending HTTP requests.

Dependencies required to test the application

Name

Version

Description

Pytest

8.3.5
Test framework for Python.

Dependencies required to build the documentation

Name

Version

Description

Sphinx

8.2.3
Tool to generate rich, well-structured, easy-to-read
documentation.

Sphinx ReadTheDocs Theme

3.0.2
A Sphinx documentation theme.

Sphinx Tabs

3.4.7
A Sphinx extension to create tabbed content in
Sphinx documentation when building HTML.

Tests

Tests on the application code can be found in the tests directory. All the tests were implemented with pytest framework. To run them, you can run the pytest command :

$ pytest

Code organisation

.
├── build_docker_image.sh
├── CHANGELOG.md
├── doc
│   ├── conf.py
│   ├── developers_guide.rst
│   ├── functions.rst
│   ├── index.rst
│   ├── overview.rst
│   ├── query_rest_api.rst
│   └── vars.rst
├── Dockerfile
├── LICENSE
├── Makefile
├── README.md
├── requirements.txt
├── resources
│   ├── env
│   │   ├── mesocentre.env
│   │   └── pfem.env
│   ├── goslin_about.json
│   ├── lipid-list.csv
│   └── metabocloud-goslin.yaml
├── sphinx-requirements.txt
├── src
│   ├── config.py
│   ├── controllers
│   │   ├── about_controller.py
│   │   ├── grammars_controller.py
│   │   ├── __init__.py
│   │   ├── root_controller.py
│   │   └── validate_controller.py
│   ├── implementation
│   │   ├── __init__.py
│   │   └── services
│   │       ├── goslin_service.py
│   │       ├── __init__.py
│   │       ├── lipidmaps_service.py
│   │       └── metadata_service.py
│   ├── __init__.py
│   ├── main.py
│   └── models
│       ├── enums
│       │   ├── __init__.py
│       │   ├── Messages.py
│       │   └── Paths.py
│       ├── __init__.py
│       └── objects
│           ├── __init__.py
│           ├── LipidMapsEntry.py
│           └── Vars.py
└── tests
    ├── data
    │   ├── expected_failed_result.json
    │   ├── expected_mixed_result.json
    │   ├── expected_successful_not_all_info_result.json
    │   ├── expected_successful_result.json
    │   └── expected_uncompleted_result.json
    ├── __init__.py
    ├── test_about_service.py
    ├── test_controllers.py
    ├── test_goslin_service.py
    └── test_lipidmaps_service.py

build_docker_image.sh

  • Script to build the Docker image in local*

CHANGELOG.md

  • File to track the different updates carried out over the course of different versions.

doc

  • Directory containing the source of the documentation

Dockerfile

  • File containing all instructions to build the application Docker image.

LICENCE

  • File containing the licence associated to the application.

Makefile

  • Configuration file to automate the execution of a set of actions.

README.md

  • File describing the project. It includes information on the purpose of the project, how it can be installed and used, where to find the documentation, etc…

requirements.txt

  • File listing all dependencies necessary for the application to work. It is also use to facilitate the installation of these dependencies.

resources : Directory containing the resources files

  • env/mesocentre.env : Environment file containing environment variables needed to run the application on the production server (host by the Mesocentre).

  • env/pfem.env : Environment file containing environment variables needed to run the application on the dev server (host by the PFEM).

  • goslin_about.json : JSON file with the metadata on the microservice and the tool.

  • metabocloud-goslin.yaml : YAML file configuring the OpenAPI specifications.

  • lipid-list.csv : CSV file containing the lipid class supported by the Pygoslin tool (retrieved from the pygoslin GitHub).

sphinx-requirements.txt

  • File listing all dependencies necessary to build the Sphinx application. It is also use in the GitLab CI/CD to only install the necessary dependencies during the job where the Sphinx documentation is built.

src : Directory containing the source code of the application

  • config.py : Module to configure the application.

  • main.py : Main application.

  • controllersPackage containing controllers

    • about_controller.py : Controller for the “/about” endpoint to retrieve the metadata associated to the REST API.

    • grammars_controller.py : Controller for the “/grammars” endpoint to retrieve the grammars available in Goslin tool.

    • root_controller.py : Controller for the “/” root endpoint.

    • validate_controller.py : Controller for the “/validate” endpoint to standardized lipid names.

  • implementation/servicesPackage containing services

    • goslin_services.py : Service regrouping methods related to the PyGoslin tool.

    • lipidmaps_service.py : Service regrouping methods to process information from the LipidMaps Structure Database.

    • metadata_service.py : Service regrouping methods related to the application metadata.

  • modelsPackage containing models
    • enumsPackage containing enumeration models

      • Messages.py : Module regrouping enumerations containing messages.

      • Paths.py : Module regrouping enumerations containing paths.

    • objectsPackage containing object models

      • LipidmapsEntry.py : An Object model to store LipidMaps Structure Database entry.

      • Vars.py : Variables used in the application.

testsDirectory containing the tests
  • dataDirectory containing expected response data.

    • expected_failed_result.json : Response data expected when a lipid failed to be parsed.

    • expected_mixed_result.json : Expected response data with all possible types of result parsing.

    • expected_successful_not_all_info_result.json : Response data expected when a lipid was parsed successfully but with some information missing.

    • expected_successful_result.json : Response data expected when a lipid was parsed successfully.

    • expected_uncompleted_result.json : Response data expected when a lipid was parsed incompletely.

  • test_about_service.py : Tests for the service managing the application metadata.

  • test_controllers.py : Tests for all controllers of the application.

  • test_goslin_service.py : Tests for the service managing the methods related to the Pygoslin tool.

  • test_lipidmaps_service.py : Tests for the services managing the methods related to the LipidMaps Structure Database.

Code documentation