magistrala/apidocs/openapi/http.yaml

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

openapi: 3.0.1
info:
  title: Magistrala http adapter
  description: |
    HTTP API for sending messages through communication channels.
    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.0

servers:
  - url: http://localhost:8008
  - url: https://localhost:8008

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

paths:
  /m/{domainPrefix}/c/{channelPrefix}:
    post:
      summary: Sends message to the communication channel
      description: |
        Sends message to the communication channel. Messages can be sent as
        JSON formatted SenML or as blob.
      tags:
        - messages
      parameters:
        - $ref: "#/components/parameters/domainPrefix"
        - $ref: "#/components/parameters/channelPrefix"
      requestBody:
        $ref: "#/components/requestBodies/MessageReq"
      responses:
        "202":
          description: Message is accepted for processing.
        "400":
          description: Message discarded due to its malformed content.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Access denied to the requested resource.
        "404":
          description: Message discarded due to invalid channel id.
        "415":
          description: Message discarded due to invalid or missing content type.
        "500":
          $ref: "#/components/responses/ServiceError"
  /health:
    get:
      summary: Retrieves service health check info.
      tags:
        - health
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HealthRes"
        "500":
          $ref: "#/components/responses/ServiceError"

components:
  schemas:
    SenMLRecord:
      type: object
      properties:
        bn:
          type: string
          description: Base Name
        bt:
          type: number
          format: double
          description: Base Time
        bu:
          type: number
          format: double
          description: Base Unit
        bv:
          type: number
          format: double
          description: Base Value
        bs:
          type: number
          format: double
          description: Base Sum
        bver:
          type: number
          format: double
          description: Version
        n:
          type: string
          description: Name
        u:
          type: string
          description: Unit
        v:
          type: number
          format: double
          description: Value
        vs:
          type: string
          description: String Value
        vb:
          type: boolean
          description: Boolean Value
        vd:
          type: string
          description: Data Value
        s:
          type: number
          format: double
          description: Value Sum
        t:
          type: number
          format: double
          description: Time
        ut:
          type: number
          format: double
          description: Update Time
    SenMLArray:
      type: array
      items:
        $ref: "#/components/schemas/SenMLRecord"

  parameters:
    domainPrefix:
      name: domainPrefix
      description: ID or route of the domain associated with the channel and client.
      in: path
      schema:
        type: string
      example: mydomain
      required: true
    channelPrefix:
      name: channelPrefix
      description: ID or route of the channel connected to the client.
      in: path
      schema:
        type: string
      example: mychannel
      required: true

  requestBodies:
    MessageReq:
      description: |
        Message to be distributed. Since the platform expects messages to be
        properly formatted SenML in order to be post-processed, clients are
        obliged to specify Content-Type header for each published message.
        Note that all messages that aren't SenML will be accepted and published,
        but no post-processing will be applied.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SenMLArray"

  responses:
    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: uuid
      description: |
        * Client access: "Authorization: Client <client_key>"

    basicAuth:
      type: http
      scheme: basic
      description: |
        * Clients access: "Authorization: Basic <base64-encoded_credentials>"

security:
  - bearerAuth: []
  - basicAuth: []