api_doc.yml

openapi: 3.0.1
info:
  title: 'Convergo Converter API'
  description: |-
    Description of the APIs provided by the **Convergo** converter for conversions:
    - From [GTFS](https://gtfs.org/documentation/schedule/reference/) to the [NeTEX Italian profile](https://github.com/5Tsrl/netex-italian-profile)
    - From [GTFS-RT](https://gtfs.org/documentation/realtime/reference/) to the [Siri Italian profile](https://github.com/5Tsrl/siri-italian-profile) (Alerts - Vehicle position - Trip updates)
    
    GitHub repository link: [Convergo](https://github.com/cefriel/convergo)

  version: "1.0"
servers:
- url: http://localhost:8080/api/v1
tags:
- name: /convergo
  description: "API for retrieving/loading feeds and initializing conversion"
paths:
  /convergo/gtfs/feed/upload/{feed}:
    post:
      tags:
      - /convergo
      operationId: upload
      summary: Initialize conversion between GTFS and NeTEx.
      description: |-
       **This API loads GTFS feeds and starts the conversion.**
       
       The feeds must be inserted into a single **.zip** file and the compressed file must not contain folders or sub-folders inside, meaning all .txt feeds must be at the first level
       
       The conversion is executed asynchronously as it can take a long time depending on the size of the loaded GTFS feeds. The call returns an identifier in case of success to check the conversion status with the dedicated REST API
      parameters:
      - name: feed
        in: path
        description: Identifier of the GTFS/GTFS-RT feeds loaded. Must be equivalent to the one used in the map name. 
        required: true
        schema:
          type: string
      - name: split
        in: query
        description: |-
          Allows you to specify the type of conversion to adopt and the possible values are:
          - **empty** Complete conversion containing all NeTEx frames
          - **frames** Separate conversion for each frame
          - **lines** Separate conversion for each line
        required: false
        schema:
            type: string
            default: "" 
            enum:
              - ""
              - frames
              - lines
      requestBody:
        content:
          application/zip:
            schema:
              # The 'binary' format is used to represent file contents
              type: string
              format: binary
      responses:
        '200':
          description: Conversion initialized successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/conversion_started"   
        '400':
          description: In case the zip file with GTFS feeds was not uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"          
        '404':
          description: In case there is no map for the feed specified in the call
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          description: In case an error occurs inside the converter.


  /convergo/netex/{conversionId}:
    get:
      tags:
      - /convergo
      operationId: status
      summary: Conversion status/download converted file
      description: |-
        **This API allows you to check the conversion status or download a file with the conversion.**
        
        If the conversion is not finished, the call will return a JSON response with details about the conversion status
        
        If the conversion is finished, a compressed file (.zip) with the conversion result will be downloaded instead
      parameters:
      - name: conversionId
        in: path
        description: Conversion identifier to retrieve the NeTEx conversion result or to download the result once it's finished.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: |-
            Conversion completed successfully. 
            
            In this case, a compressed file containing one or more files will be downloaded depending on whether a complete conversion, by frame, or by line was requested.
            
            If the conversion is in progress, a JSON with details will be returned instead
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/conversion_in_progress"   

  /convergo/siri-et/{feed}:
    get:
      tags:
      - /convergo
      operationId: siri-et
      summary: Conversion from GTFS-RT to SIRI - Trip Updates
      description: |-
        **This API allows you to perform the conversion of GTFS-RT feeds related to Trip Updates in SIRI format**
        
        It is possible to specify through the optional parameter whether to also integrate static GTFS data in the conversion.
      parameters:
      - name: feed
        in: path
        description: Identifier of the feed related to <b>Trip updates</b> to be converted to the SIRI standard. Must be equivalent to the one used in the map name. 
        required: true
        schema:
          type: string
      - name: gtfs
        in: query
        description: Specifies whether to access GTFS feeds to enrich SIRI output. If not specified or any other value different from the string **true** will be evaluated as false
        required: false
        schema:
            type: string
            default: "false" 
            enum:
              - "false"
              - "true"
      responses:
        '200':
          description: |-
            Conversion completed successfully.
            In this case, the XML file containing the conversion from GTFS-RT to SIRI - Trip Updates will be provided
        '404':
          description: "In case no URL is specified in the map for retrieving GTFS-RT data related to Trip Updates"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          description: In case an error occurs inside the converter.
   
  /convergo/siri-sx/{feed}:
    get:
      tags:
      - /convergo
      operationId: siri-sx
      summary: Conversion from GTFS-RT to SIRI - Service alerts
      description: |-
        **This API allows you to perform the conversion of GTFS-RT feeds related to Service alerts in SIRI format**
        
        It is possible to specify through the optional parameter whether to also integrate static GTFS data in the conversion.
      parameters:
      - name: feed
        in: path
        description: Identifier of the feed related to <b>Service alerts</b> to be converted to the SIRI standard. Must be equivalent to the one used in the map name. 
        required: true
        schema:
          type: string
      - name: gtfs
        in: query
        description: Specifies whether to access GTFS feeds to enrich SIRI output. If not specified or any other value different from the string **true** will be evaluated as false
        required: false
        schema:
            type: string
            default: "false" 
            enum:
              - "false"
              - "true"
      responses:
        '200':
          description: |-
            Conversion completed successfully.
            In this case, the XML file containing the conversion from GTFS-RT to SIRI - Service alerts will be provided
        '404':
          description: "In case no URL is specified in the map for retrieving GTFS-RT data related to Service alerts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          description: In case an error occurs inside the converter.
  /convergo/siri-vm/{feed}:
    get:
      tags:
      - /convergo
      operationId: siri-sx
      summary: Conversion from GTFS-RT to SIRI - Vehicle positions
      description: |-
        **This API allows you to perform the conversion of GTFS-RT feeds related to Vehicle positions in SIRI format**
        
        It is possible to specify through the optional parameter whether to also integrate static GTFS data in the conversion.
      parameters:
      - name: feed
        in: path
        description: Identifier of the feed related to <b>Vehicle positions</b> to be converted to the SIRI standard. Must be equivalent to the one used in the map name.
        required: true
        schema:
          type: string
      - name: gtfs
        in: query
        description: Specifies whether to access GTFS feeds to enrich SIRI output. If not specified or any other value different from the string **true** will be evaluated as false
        required: false
        schema:
            type: string
            default: "false" 
            enum:
              - "false"
              - "true"
      responses:
        '200':
          description: |-
            Conversion completed successfully.
            In this case, the XML file containing the conversion from GTFS-RT to SIRI - Vehicle positions will be provided
        '404':
          description: "In case no URL is specified in the map for retrieving GTFS-RT data related to Vehicle positions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          description: In case an error occurs inside the converter.
components:
  schemas:
    Error:
      type: object
      properties:
        status_code:
          type: string
        message:
          type: string
        details:
          type: string
    conversion_started:
      type: object
      properties:
        status_code:
          type: integer
          format: int64
          example: 200
        message:
          type: string
          example: GTFS feeds for [feed] loaded correctly and conversion started. The conversion may take time. Check the status with the dedicated REST API using the conversion ID
        details:
          type: string
          example: "[feed]_1234567890"
    conversion_in_progress:
      type: object
      properties:
        status_code:
          type: integer
          format: int64
          example: 200
        message:
          type: string
          example: "The NeTEx conversion is still in progress...."
        details:
          type: string
          example: "Conversion ID: [feed]_1234567890"