HolobiomicsLab HTTP API Endpoint Design
Summary
Design and implement RESTful HTTP POST endpoints that accept file uploads with spectral data, validate input formats, process the data through a computational pipeline, and return compressed artifact collections. This skill bridges client requests for spectral analysis with backend processing services.
When to use
When you need to expose a multi-step spectral processing workflow (parse → extract → render → annotate → compress) as a web service endpoint that accepts jcamp/RAW/mzML spectral files and must return coordinated output artifacts (modified JCAMP files, peak tables, and PNG images) in a single response.
When NOT to use
- Input spectral data is already in a processed binary format incompatible with the chem-spectra-app parser
- Client application requires streaming or real-time response rather than a single atomic payload
- Output artifacts exceed practical ZIP archive size limits for your deployment environment
Inputs
- POST request body with spectral file attachment (.dx or .jdx JCAMP format)
- Spectral data in jcamp, RAW, or mzML format
Outputs
- ZIP archive containing modified JCAMP file(s) with peak annotations
- PNG image renderings of spectral data with annotated peaks
- Peak table artifacts
How to apply
Define a POST endpoint (e.g., /zip_jcamp_n_img) that receives a spectral file attachment (.dx or .jdx format). Parse and validate the input using a dedicated file parser (chem-spectra-app). Extract spectral peaks and generate peak tables from the parsed data. Render the spectral data as PNG images with annotated peaks. Incorporate peak table annotations into modified JCAMP output file(s). Compress all output artifacts (JCAMP and PNG files) into a single ZIP archive. Return the ZIP with appropriate MIME type and HTTP headers. This design ensures the client receives all derived data products in one atomic transaction, reducing round-trip overhead.
Related tools
- Flask (Web framework for defining and routing the HTTP POST endpoint) — https://github.com/ComPlat/chem-spectra-app
- chem-spectra-app (File parser and spectral data processor; validates input formats and extracts peaks) — https://github.com/ComPlat/chem-spectra-app
- proteowizard/pwiz-skyline (Docker containerized service for handling RAW and mzML mass spectrometry file formats) — https://github.com/ComPlat/chem-spectra-app
- gunicorn (WSGI HTTP server for deploying the Flask endpoint in production) — https://github.com/ComPlat/chem-spectra-app
Examples
curl -X POST -F 'file=@spectrum.jdx' http://localhost:3007/zip_jcamp_n_img -o output.zip
Evaluation signals
- HTTP POST request to the endpoint returns status 200 with a valid ZIP archive in the response body
- ZIP archive contains expected files: at least one modified JCAMP file and one PNG image per input spectrum
- Response MIME type is 'application/zip' and Content-Disposition header specifies appropriate filename
- Peak table data extracted from JCAMP is non-empty and matches the annotations rendered in PNG images
- Input validation rejects malformed or unsupported file formats (not jcamp/RAW/mzML) with a descriptive HTTP 400 error
Limitations
- Endpoint design assumes single spectral file input per request; handling multiple files in one request requires additional multiplexing logic
- RAW and mzML file processing depends on proteowizard/pwiz-skyline Docker service availability and correct environment configuration
- No explicit timeout or file size limits mentioned; large spectral files may cause memory exhaustion or slow response times
- Peak annotation accuracy and PNG rendering quality are dependent on upstream chem-spectra-app parser correctness and configuration
Evidence
- [other] Receive POST request with spectral file attachment in .dx or .jdx format at the /zip_jcamp_n_img endpoint: "Receive POST request with spectral file attachment in .dx or .jdx format at the /zip_jcamp_n_img endpoint."
- [other] Parse and validate the input spectral file format using the chem-spectra-app file parser: "Parse and validate the input spectral file format using the chem-spectra-app file parser."
- [other] Extract spectral peaks and generate peak tables from the parsed data: "Extract spectral peaks and generate peak tables from the parsed data."
- [other] Generate PNG image renderings of the spectral data with annotated peaks: "Generate PNG image renderings of the spectral data with annotated peaks."
- [other] Compress all output artifacts (JCAMP files and PNG images) into a single ZIP file: "Compress all output artifacts (JCAMP files and PNG images) into a single ZIP file."
- [readme] This backend web service provides NMR/IR/MS processing for jcamp/RAW/mzML files: "This backend web service provides NMR/IR/MS processing for jcamp/RAW/mzML files."
- [other] Return the ZIP archive to the client with appropriate MIME type and headers: "Return the ZIP archive to the client with appropriate MIME type and headers."