magistrala/api/openapi/http.yml

# 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@mainflux.com
  license:
    name: Apache 2.0
    url: https://github.com/absmach/magistrala/blob/master/LICENSE
  version: 0.14.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: http://docs.mainflux.io/
      
paths:
  /channels/{id}/messages:
    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/ID"
      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.
        "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
      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:
    ID:
      name: id
      description: Unique channel identifier.
      in: path
      schema:
        type: string
        format: uuid
      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/json:
          schema:
            $ref: "./schemas/HealthInfo.yml"

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

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

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