MassBank-export-api

A REST interface to export MassBank records to other formats.

This server was generated by the OpenAPI Generator project and uses Spring Boot. It uses the RecordParserDefinition from the original MassBank project.

Requirements

• Java 21
• Spring Boot 3.5
• maven
• PostgreSQL (tested on version 17)

Configuration

MassBank Data

This microservice is configured with environment variables. It requires a directory with the MassBank-data release. This directory needs to be configured in the environment variable MB_DATA_DIRECTORY.

git clone https://github.com/MassBank/MassBank-data.git
export MB_DATA_DIRECTORY="$(realpath ./MassBank-data)"

CORS

To configure CORS you can set the environment variable CORS_ALLOWED_ORIGINS.

export CORS_ALLOWED_ORIGINS=http://localhost:3000

CONTEXT_PATH

The application serves the content at the given CONTEXT_PATH. If no CONTEXT_PATH is given the application serves at root path http://localhost:8080/. To serve the application at a different path set the environment variable CONTEXT_PATH, e.g. CONTEXT_PATH="/MassBank-export and the server will listen on http://localhost:8080/MassBank-export.

Using a Reverse Proxy

To make the Swagger UI work behind a reverse proxy one must configure some X-Forward RequestHeader as descibed here. Here is an example for Apache:

RequestHeader set X-Forwarded-Prefix "/MassBank-export"
RequestHeader set X-Forwarded-Proto https
RequestHeader set X-Forwarded-Port 443

To make this work with a K8s nginx Ingress one needs to enable the property

use-forwarded-headers true

in the ingress-nginx-controller ConfigMap. The application context path can be configured with the environment variable CONTEXT_PATH. If not set / is used by default.

PostgreSQL

Make sure to have a PostgreSQL server installed and running on your system. The MassBank data will be stored there.

By default, the export service expects the PostgreSQL service running at localhost with port 5432 and the database records. Default user is massbank_export_api_user and password is massbank-export-api-password.

Build and Run

Build the service with Maven:

mvn clean package

This build creates two executable jars:

• target/massbank-export-api-rest-api.jar
• target/massbank-export-api-data-import.jar

Import the MassBank records into the configured PostgreSQL database once before starting the REST API:

java -jar target/massbank-export-api-data-import.jar

Run the REST API:

java -jar target/massbank-export-api-rest-api.jar

Run with Docker

Build and Run

The file docker-compose.yml provides the config to build and run the postgres database and the MassBank-export-api with docker. Copy env.dist file to .env file and configure to your needs. Then build and run with:

docker compose up --build

This starts PostgreSQL and the REST API service. The importer is available as a separate on-demand service profile.

Run the importer profile when you want to (re)load data:

docker compose --profile import up --build data-loader

Both services use one Docker image that contains two jars:

• export-service runs /app-rest.jar
• data-loader runs /app-import.jar

Then start or restart the REST API:

docker compose up --build export-service

Use Pre-built Container

Pre-built Docker images are available from quay.io/massbank/massbank-export-api. The fastest way to get things running after creating .env is:

docker compose up

To run only the importer from the pre-built image:

docker compose --profile import up data-loader

Usage

For a description of how to use the api browse to the Swagger UI.

The database status can be checked with:

curl http://localhost:8080/database/status

For readiness checks use:

curl -i http://localhost:8080/database/ready

/database/ready returns HTTP 200 when the database is reachable and contains active MassBank records, otherwise HTTP 503.

For example, to download all MassBank records in one zip file use the following command:

curl -X 'POST' \
  'http://localhost:8080/convert' \
  -H 'accept: application/zip' \
  -H 'Content-Type: application/json' \
  -d '{
  "format": "massbank"
}' --output records.zip

Or, for example, to get a record's raw text use the following command:

curl -X 'GET' \
  'http://localhost:8080/rawtext/MSBNK-IPB_Halle-PB001341' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json'