openapi: 3.0.3

###############################################################################
## METADATA AND DOCUMENTATION

info:
  title: InDex REST-API documentation
  version: 1.0.0
  description: REST-API to retrieve metabolite structure/representation files from a customized S3 storage containing data from different communities.
  contact:
    name: MetaboCloud
    email: contact@peakforest.org
    url: https://metabocloud.mesocentre.uca.fr/
  license:
    name: MIT License
    url: https://opensource.org/license/mit/

externalDocs:
  description: InDex - Users - REST API official "ReadTheDocs" documentation
  url: https://metabocloud.mesocentre.uca.fr/index/readthedocs/overview.html

###############################################################################
## SERVICES AND SERVERS

servers:
  - url: https://metabocloud.mesocentre.uca.fr/index

tags:
  - name: metadata
    description: REST API metadata endpoint
  - name: index
    description: REST API core endpoints

###############################################################################
## PATHS

paths:
  /about:
    $ref: https://metabocloud.mesocentre.uca.fr/staticcontent/about.yaml#/paths/~1about

  /compounds/{inchiKey}.{format}:
    get:
      tags:
        - index
      summary: Retrieve a structure/representation file of a compound from its InChI Key (e.g. PNG image, MOL file).
      description: |
        This endpoint allows to fetch a compound's file (PNG image or MOL file) with associated metadata from a specific community using its **InChI Key**. 
        
        ### Available format

        The files can be retrieved in two formats :
        - **PNG image** : a visual representation of the molecule.
        - **MOL file** : a chemical structure file format used to describe the structure of a molecule.

        ### Available community

        Currently, there is only one community available :
        - **chebi**: which provides files from the Chemical Entities of Biological Interest (ChEBI) database.

        ### Metadata in Response Headers

        The response includes metadata in the headers for each retrieved file :

        - **Common metadata** :
          - `X-Metadata-Creation-Date` : The date on which the file was saved in storage (YYYY-MM-DD).
          - `X-Metadata-Data-License` : The license of the file.
          - `X-Metadata-Data-Source` : The source of the file.

        - **For the `chebi` community only** :
          - `X-Metadata-Chebi-Id` : The **ChEBI ID** associated to the file. 

        - **For the `png` format only** :
          - `X-Metadata-Image-Size` : The image size in pixels (XXX x XXX px).

        This allows to get additional information about the retrieved file.

        ### Example Use Case

        To fetch the **PNG image** of the *Caffeine* molecule with its **InChI Key** `RYYVLZVUVIJVGH-UHFFFAOYSA-N` from the **chebi** community in **medium** size as a resource :

        #### Request :
        ```
        GET /compounds/RYYVLZVUVIJVGH-UHFFFAOYSA-N.png?community=chebi&size=medium&outputType=resource
        ```
        #### Response :
        - If the file is found, the response will contain the PNG image as a resource with relevant headers.
        - If not found, a `404 Not Found` error will be returned.

        ##### Metadata in Response Headers :

        ```
        X-Metadata-Chebi-Id: 90
        X-Metadata-Creation-Date: 2024-08-26
        X-Metadata-Data-License: Creative Commons License (CC BY 4.0)
        X-Metadata-Data-Source: Chemical Entities of Biological Interest (ChEBI) Database
        X-Metadata-Image-Size: 350 x 350 px
        ```
      operationId: getFile
      parameters:
        - in: path
          name: inchiKey
          schema:
            type: string
          required: true
          description: The **InChI Key** of the compound you want to retrieve.
          example: RYYVLZVUVIJVGH-UHFFFAOYSA-N
        - in: path
          name: format
          schema:
            type: string
            enum:
              - png
              - mol
          required: true
          description: |
            The **format of the file** you want to retrieve. It accepts either :
              - `png`: For a PNG image.
              - `mol`: For a MOL file.
        - in: query
          name: community
          schema:
            type: string
            enum:
              - chebi
            default: chebi
          description: |
            The **community** from which the file originates.  
            Currently, only `chebi` is supported which provides files from the Chemical Entities of Biological Interest (ChEBI) database.
        - in: query
          name: size
          schema:
            type: string
            enum:
              - small
              - medium
              - large
            default: medium
          description: |
            The **size of the PNG image**. It can be :
              - `small`: 50 x 50 pixels
              - `medium`: 350 x 350 pixels
              - `large`: 700 x 700 pixels
          
            Applicable only for PNG format ; not required for MOL files.
        - in: query
          name: outputType
          schema:
            type: string
            enum:
              - resource
              - url
            default: url
          description: |
              How the file is returned. It can be either:
                - `resource`: Returns the actual file content (e.g the PNG image).
                - `url`: Returns a URL pointing to the file (e.g the URL of the PNG image).
      responses:
        "200":
          description: The wanted file is successfully returned.
          headers:
            X-Metadata-Chebi-Id:
              schema:
                type: string
              description: The ChEBI ID associated to the file (only for the "chebi" community).
            X-Metadata-Creation-Date:
              schema:
                type: string
              description: The date on which the file was saved in storage (YYYY-MM-DD).
            X-Metadata-Data-License:
              schema:
                type: string
              description:  The license of the file.
            X-Metadata-Data-Source:
              schema:
                type: string
              description: The source of the file.
            X-Metadata-Image-Size:
              schema:
                type: string
              description: The image size in pixels (XXX x XXX px).

          content:
            image/png:
              schema:
                type: string
                format: binary
            plain/text:
              schema:
                type: string
        "400":
          description: Bad Request - Parameters Error
        "404":
          description: Not Found - The file requested does not exist