# Copyright (c) Abstract Machines
# SPDX-License-Identifier: Apache-2.0

openapi: 3.0.1
info:
  title: Magistrala reader service
  description: |
    HTTP API for reading messages.
    Some useful links:
    - [The Magistrala repository](https://github.com/absmach/magistrala)
  contact:
    email: info@absmach.eu
  license:
    name: Apache 2.0
    url: https://github.com/absmach/magistrala/blob/main/LICENSE
  version: 0.18.5

servers:
  - url: http://localhost:9003
  - url: https://localhost:9003
  - url: http://localhost:9005
  - url: https://localhost:9005
  - url: http://localhost:9009
  - url: https://localhost:9009
  - url: http://localhost:9011
  - url: https://localhost:9011

tags:
  - name: readers
    description: Everything about your Readers
    externalDocs:
      description: Find out more about readers
      url: https://magistrala.absmach.eu/docs/

paths:
  /{domainID}/channels/{chanId}/messages:
    get:
      operationId: getMessages
      summary: Retrieves messages sent to single channel
      description: |
        Retrieves a list of messages sent to specific channel. Due to
        performance concerns, data is retrieved in subsets. The API readers must
        ensure that the entire dataset is consumed either by making subsequent
        requests, or by increasing the subset size of the initial request.
      tags:
        - readers
      parameters:
        - $ref: "#/components/parameters/DomainID"
        - $ref: "#/components/parameters/ChanId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Publisher"
        - $ref: "#/components/parameters/Name"
        - $ref: "#/components/parameters/Value"
        - $ref: "#/components/parameters/BoolValue"
        - $ref: "#/components/parameters/StringValue"
        - $ref: "#/components/parameters/DataValue"
        - $ref: "#/components/parameters/From"
        - $ref: "#/components/parameters/To"
        - $ref: "#/components/parameters/Aggregation"
        - $ref: "#/components/parameters/Interval"
      responses:
        "200":
          $ref: "#/components/responses/MessagesPageRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "500":
          $ref: "#/components/responses/ServiceError"
  /health:
    get:
      operationId: health
      summary: Retrieves service health check info.
      tags:
        - health
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HealthRes"
        "500":
          $ref: "#/components/responses/ServiceError"

components:
  schemas:
    MessagesPage:
      type: object
      properties:
        total:
          type: number
          description: Total number of items that are present on the system.
        offset:
          type: number
          description: Number of items that were skipped during retrieval.
        limit:
          type: number
          description: Size of the subset that was retrieved.
        messages:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            type: object
            properties:
              channel:
                type: integer
                description: Unique channel id.
              publisher:
                type: integer
                description: Unique publisher id.
              protocol:
                type: string
                description: Protocol name.
              name:
                type: string
                description: Measured parameter name.
              unit:
                type: string
                description: Value unit.
              value:
                type: number
                description: Measured value in number.
              stringValue:
                type: string
                description: Measured value in string format.
              boolValue:
                type: boolean
                description: Measured value in boolean format.
              dataValue:
                type: string
                description: Measured value in binary format.
              valueSum:
                type: number
                description: Sum value.
              time:
                type: number
                description: Time of measurement.
              updateTime:
                type: number
                description: Time of updating measurement.

  parameters:
    DomainID:
      name: domainID
      description: Unique domain identifier.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    ChanId:
      name: chanId
      description: Unique channel identifier.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    Limit:
      name: limit
      description: Size of the subset to retrieve.
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      required: false
    Offset:
      name: offset
      description: Number of items to skip during retrieval.
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      required: false
    Publisher:
      name: Publisher
      description: Unique thing identifier.
      in: query
      schema:
        type: string
        format: uuid
      required: false
    Name:
      name: name
      description: SenML message name.
      in: query
      schema:
        type: string
      required: false
    Value:
      name: v
      description: SenML message value.
      in: query
      schema:
        type: string
      required: false
    BoolValue:
      name: vb
      description: SenML message bool value.
      in: query
      schema:
        type: boolean
      required: false
    StringValue:
      name: vs
      description: SenML message string value.
      in: query
      schema:
        type: string
      required: false
    DataValue:
      name: vd
      description: SenML message data value.
      in: query
      schema:
        type: string
      required: false
    Comparator:
      name: comparator
      description: Value comparison operator.
      in: query
      schema:
        type: string
        default: eq
        enum:
          - eq
          - lt
          - le
          - gt
          - ge
      required: false
    From:
      name: from
      description: SenML message time in nanoseconds (integer part represents seconds).
      in: query
      schema:
        type: number
      example: 1709218556069
      required: false
    To:
      name: to
      description: SenML message time in nanoseconds (integer part represents seconds).
      in: query
      schema:
        type: number
      example: 1709218757503
      required: false
    Aggregation:
      name: aggregation
      description: Aggregation function.
      in: query
      schema:
        type: string
        enum:
          - MAX
          - AVG
          - MIN
          - SUM
          - COUNT
          - max
          - min
          - sum
          - avg
          - count
      example: MAX
      required: false
    Interval:
      name: interval
      description: Aggregation interval.
      in: query
      schema:
        type: string
      example: 10s
      required: false

  responses:
    MessagesPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MessagesPage"
    ServiceError:
      description: Unexpected server-side error occurred.
    HealthRes:
      description: Service Health Check.
      content:
        application/health+json:
          schema:
            $ref: "./schemas/health_info.yaml"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        * Users access: "Authorization: Bearer <user_token>"

    thingAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: |
        * Things access: "Authorization: Thing <thing_key>"

security:
  - bearerAuth: []
  - thingAuth: []