logs_ingestor__v1.yml

openapi: 3.0.0
info:
  version: "1"
  title: "LogsIngestor"
  description: >
    An API to ingest logs, via HTTP. Mostly used by frontend apps. </br></br>
    </br></br>
    Notes - </br></br>
    
    The backend side will accept an array of logs, and will use logger to persist messages to ElasticSearch </br>
    
    The 'ingest' endpoint will not throw 500, if some of the logs were not persisted successfully (event if all). Some retry mechanism should be implemente on the backend side. If we are not able to persist message after a reasonable amount of retries, just log to SDTOUT. </br>
    
    The 'ingest' should not be syncronous, to not introduce long running http requests and big latency calls. If that is possible, return 204 to client immidiatelly, and process logs in a background. </br>
    
    Ingest logs schema reflects logger interface (not sure about datetime).
servers:
  - url: http://rollun-net-prvt/openapi/LogsIngestor/v1
  - url: http://node-red:80/openapi/LogsIngestor/v1
  - url: https://rollun.net/api/openapi/LogsIngestor/v1
tags:
  - name: LogsIngestor
paths:
  "/ingest":
    post:
      tags:
        - LogsIngestor
      summary: "Ingest multiple log entries"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogsIngestRequest'
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
        "500":
          description: "Internal error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
      description: "Message field is not required"
    SuccessResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      type: object
      properties:
        data:
          type: object
    SimpleResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
      type: object
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/Result'

    Message:
      type: object
      properties:
        level:
          type: string
          enum:
            - emergency
            - alert
            - critical
            - error
            - warning
            - notice
            - info
        type:
          type: string
          enum:
            - UNDEFINED
            - INVALID_RESPONSE
          description: >
            UNDEFINED - Any undefined message type
            INVALID_RESPONSE - A message generated by the client stating that the response could not be decoded
        text:
          type: string
          description: Message, that describes what went wrong

    LogsIngestRequest:
      type: object
      properties:
        logs:
          type: array
          maxLength: 50
          items:
            $ref: '#/components/schemas/Log'

    Log:
      type: object
      required:
        - service
        - message
        - level
        - lifecycleToken
        - parentLifecycleToken
      properties:
        service:
          description: Service name, used to identify the app (serice) that logs
          type: string
          example: 'barcodes-ui'
        level:
          type: string
          enum:
            - emergency
            - alert
            - critical
            - error
            - warning
            - notice
            - info
            - debug
        message:
          example: 'app crashed'
          description: A short description of log message. Keep it short and undestandable
          type: string
        datetime:
          description: A time of log. Optional, will be set to current UTC, if not specified. Usefull when batching
          type: string
          format: date-time
        context:
          description: >
            A free object with any data in addition to message. Defaults to empty {} JS object
            If context is too big for internal logger, it is expected that log will be saved anyway,
            but truncated.
          type: object
          additionalProperties: true
          example:
            user:
              email: user@mail.dev
              roles:
                - guest
            stacktrace: >
              some/path/a.js
              some/path/b.js
            error: cannot read property of undefined
        serviceVersion:
          description: >
            a string that represents a version of client application.
            Frontend is not immidiatelly updated, so it is usefull to know what varsion is used.
            added to the top level of log object (not context) on the same level as message.
          example: 'v1.2.3'
          type: string
        lifecycleToken:
          example: 'ui-request-77ce8821-47a2-46d5-b526-8af6af34ae7e'
          description: >
            A unique string, that represents a request to the backend API. Must be generated on each request
            Always starts with 'ui-request-'
          type: string
        parentLifecycleToken:
          example: 'ui-session-77ce8821-47a2-46d5-b526-8af6af34ae7e'
          description: >
            A unique string, that represents user session. Always starts with 'ui-session-'
          type: string

    Result:
      type: object
      properties:
        result:
          type: boolean