openapi: 3.0.3

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

info:
  title: CDK REST-API documentation
  version: 2.9.0
  description: 'REST-API of CDK, "Chemistry Development Kit", which is a collection of modular Java libraries for processing chemical information.'
  contact:
    name: MetaboCloud
    email: faustine.souc@inrae.fr
    url: https://metabocloud.mesocentre.uca.fr/
  license:
    name: GNU Lesser General Public License v2.1 
    url: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html

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

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

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

tags:
  - name: metadata 
    description: Metadata about the microservice
  - name: cdk
    description: REST API wrapper for CDK tool

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

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

  /mass/{formula}:
    get:
      tags:
        - cdk
      summary: Compute masses from the formula of a compound
      description: Compute the average and monoisotopic masses from a compound's raw formula.
      operationId: massFromFormula
      parameters:
        - in: path
          name: formula
          required: true
          schema:
            type: string
            description: The compound's formula
            example: C8H10N4O2
      responses:
        '200':
          description: The masses were successfully computed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CdkMassResponse'
        '400':
          description: Bad Request - Invalid parameter

  /properties:
    post:
      tags:
        - cdk
      summary: Retrieve the chemical properties of a molecule.
      description: |
        Retrieve chemical information about a molecule from an InCHI, a MOL or a SDF file :

          * The **sum formula** of the molecule
          * The **monoisotopic mass** of the molecule
          * The **average mass** of the molecule
          * The **canonical SMILES** of the molecule
          * The **stereochemical SMILES** of the molecule
          * The **InCHI key** of the molecule
          * The **LogP** of the molecule
      operationId: computeProperties
      requestBody:
        description: "**Only `one` of the following parameters is expected in the request body.**"
        required: true
        content:
           multipart/form-data:
              schema:
               $ref : '#/components/schemas/MultipartInput'
      responses:
        '200':
          description: | 
            The chemical properties were successfully computed. 
               
            **Note :** The result obtained may differed depending on the type of input used.  
            *e.g. A MOL or SDF file gives more detailed SMILES than an InChI.*
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CdkPropertiesResponse'
        '400':
          description: Bad Request - Error in the Request Body or Input Invalid

  /depiction/{format}:
    post:
      tags:
        - cdk
      summary: Realize a depiction of a chemical compound.
      description: | 
        Return a 2D representation of a chemical compound from its InChI, MOL or SDF file.  
        The output image is either in PNG or SVG format.
      parameters:
        - in : path
          name: format
          schema:
            type: string
            enum: 
              - png
              - svg
          required : true
          description : The image format wanted.
        - in : query
          name: width
          schema:
            type: integer
            default: 500
          description : The width of the output image (px).
        - in : query
          name: height
          schema:
            type: integer
            default: 500
          description: The height of the output image (px).
        - in : query
          name: hydrogenDisplay
          schema:
            type: string
            enum:
              - minimal
              - non-chiral
              - cdk-default
            default: non-chiral
          description: | 
            The way hydrogens are displayed.

              * **minimal** : Suppress any explicit hydrogens
              * **non-chiral** : Suppress explicit non stereo-relevant hydrogens
              * **cdk-default** : CDK default way to display hydrogens
      operationId: depictMolecule
      requestBody:
        description: "**Only `one` of the following parameters is expected in the request body.**"
        required: true
        content:
           multipart/form-data:
              schema:
                $ref : '#/components/schemas/MultipartInput'

      responses:
        '200':
          description: |
           The depiction of the molecule was successful. 
           The output is an image, either in PNG or SVG format, representing the molecule.
          content:
            image/png:
              schema: 
               type: string
               format: binary
            image/svg+xml:
              schema: 
               type: string
               format: text/xml
        '400':
          description: Bad Request - Error in the Request Body, Input Invalid or Format Output Invalid

  /conversion/{format}:
    post:
      tags:
        - cdk
      summary: Realize a conversion of a molecular structural representation format into another.
      description: Convert a format of molecular structural representation (InChI, MOL/SDF file) into another one (InChI, InChI Key, MOL/SDF file).
      parameters:
        - in : path
          name: format
          schema:
            type: string
            enum: 
              - inchi
              - inchikey
              - mol
              - sdf
          required : true
          description : The molecular structural representation format wanted.
      operationId: convertMolecule
      requestBody:
        description: "**Only `one` of the following parameters is expected in the request body.**"
        required: true
        content:
           multipart/form-data:
              schema:
                 $ref : '#/components/schemas/MultipartInputConversion'
      responses:
        '200':
          description: | 
            The conversion was successful.
            The possible output are : the InChI, the InChI Key, the MOL or the SDF.
          content:
            text/plain:
              schema:
                type : string
        '400':
          description: Bad Request - Error in the Request Body, Input Invalid or Format Output Invalid

###############################################################################
## COMPONENTS
components:
  schemas:       
    MultipartInput:
      type: object
      properties:
        inchi:
          type: string
          description: The InChI of a chemical compound.
          example: InChI=1S/C8H10N4O2/c1-10-4-9-6-5(10)7(13)12(3)8(14)11(6)2/h4H,1-3H3
        molText:
          type: string
          description: The content of a MOL file in plain text of a chemical compound.
        molFile:
          type: string
          format: binary
          description: The path to a chemical compound MOL file.
        sdfFile:
          type: string
          format: binary
          description: The path to a chemical compound SDF file.
    
    MultipartInputConversion:
      allOf:
        - $ref: '#/components/schemas/MultipartInput'
        - type: object
          properties:
            properties:
              type: string
              description: |
                The properties associated to the compound in a file.
                It must have one property by line following the structure "key : value"

    CdkMassResponse:
      type: object
      properties:
        monoisotopic_mass:
          type: number
          format: double
          description: Monoisotopic mass of the molecule
          example: 194.08037556
        average_mass:
          type: number
          format: double
          description: Average mass of the molecule
          example: 194.1909173958447
        CDK_version:
          type: string
          description : Version of CDK used to calculate these masses
          example: "2.9"
    
    CdkPropertiesResponse:
      type: object
      properties:
        state:
          type : string
          enum:
            - Success
            - Failure
          description: State of the analysis
        formula:
          type: string
          description: Formula of the molecule
          example: C8H10N4O2
        monoisotopic_mass:
          type: number
          format: double
          description: Monoisotopic mass of the molecule
          example: 194.08037556
        average_mass:
          type: number
          format: double
          description: Average mass of the molecule
          example: 194.1909173958447
        canonical_smiles:
          type: string
          description: Canonical SMILES of the molecule
          example: O=C1C2=C(N=CN2C)N(C(=O)N1C)C
        stereo_smiles:
          type: string
          description: SMILES of the molecule with the stereochemistry types supported.
          example: CN1C=NC2=C1C(N(C)C(N2C)=O)=O
        inchi:
          type: string
          description: InCHI of the molecule
          example: InChI=1S/C8H10N4O2/c1-10-4-9-6-5(10)7(13)12(3)8(14)11(6)2/h4H,1-3H3
        inchikey:
          type: string
          description: InCHI Key of the molecule
          example: RYYVLZVUVIJVGH-UHFFFAOYSA-N
        logP:
          type: number
          format: double
          description: Log P
          example: -0.10858213188126853
        CDK_version:
          type: string
          description : Version of CDK used to calculate these properties
          example: "2.9"
       
