swagger: "2.0"
info:
  version: "1.0.0"
  title: "APIClarity Plugins telemetries API"

basePath: /api

schemes:
  - http

consumes: [ "application/json" ]
produces: [ "application/json" ]

paths:
  /telemetry:
    post:
      summary: 'Post an http telemetry'
      parameters:
        - $ref: '#/parameters/TraceSourceTokenHeader'
        - in: 'body'
          name: 'body'
          required: true
          schema:
            description: 'Telemetry'
            $ref: '#/definitions/Telemetry'
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: '#/responses/Success'
        default:
          $ref: '#/responses/UnknownError'

  /hostsToTrace:
    get:
      summary: 'Get a list of hosts to trace'
      parameters:
        - $ref: '#/parameters/TraceSourceTokenHeader'
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: '#/definitions/HostsToTrace'
        default:
          $ref: '#/responses/UnknownError'

  /control/newDiscoveredAPIs:
    post:
      summary: 'Allows a client to notify APIClarity about new APIs.'
      description: 'This allows a client (a gateway for example) to notify APIclarity about newly discovered APIs. If one of the APIs already exists, it is ignored.'
      parameters:
        - $ref: '#/parameters/TraceSourceTokenHeader'
        - in: 'body'
          name: 'body'
          description: 'List of new discovered APIs'
          required: true
          schema:
            type: 'object'
            required:
              - hosts
            properties:
              hosts:
                type: 'array'
                description: 'List of discovered APIs, format of hostname:port'
                items:
                  type: 'string'
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: '#/responses/Success'
        default:
          $ref: '#/responses/UnknownError'

definitions:
  Telemetry:
    type: 'object'
    properties:
      requestID:
        type: 'string'
      scheme:
        type: 'string'
      destinationAddress:
        type: 'string'
      destinationNamespace:
        type: 'string'
      sourceAddress:
        type: 'string'
      request:
        $ref: '#/definitions/Request'
      response:
        $ref: '#/definitions/Response'

  Request:
    type: 'object'
    properties:
      method:
        type: 'string'
      path:
        type: 'string'
      host:
        type: 'string'
      common:
        $ref: '#/definitions/Common'

  Response:
    type: 'object'
    properties:
      statusCode:
        type: 'string'
      common:
        $ref: '#/definitions/Common'

  Common:
    type: 'object'
    properties:
      version:
        type: 'string'
      headers:
        type: 'array'
        items:
          $ref: '#/definitions/Header'
      body:
        type: 'string'
        format: 'byte'
      TruncatedBody:
        type: 'boolean'
      time:
        description: 'Time since epoch (milliseconds)'
        type: 'integer'
        format: int64

  Header:
    type: 'object'
    properties:
      key:
        type: 'string'
      value:
        type: 'string'

  ApiResponse:
    description: 'An object that is return in all cases of failures.'
    type: 'object'
    properties:
      message:
        type: 'string'


  SuccessResponse:
    description: 'An object that is return in cases of success that return nothing.'
    type: 'object'
    properties:
      message:
        type: 'string'

  HostsList:
    description: 'List of hosts'
    type: 'array'
    items:
      type: string
  
  HostsToTrace:
    description: 'List of hosts to trace'
    type: 'object'
    properties:
      hosts:
        $ref: '#/definitions/HostsList'
    required:
      - hosts

responses:
  UnknownError:
    description: 'unknown error'
    schema:
      $ref: '#/definitions/ApiResponse'
  Success:
    description: 'success message'
    schema:
      $ref: '#/definitions/SuccessResponse'

parameters:
  TraceSourceTokenHeader:
    name: 'X-Trace-Source-Token'
    description: 'Optional header to authenticate the trace source'
    in: 'header'
    type: 'string'
    required: false