supermq/api/openapi/provision.yml

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

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

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

tags:
  - name: provision
    description: Everything about your Provision
    externalDocs:
      description: Find out more about provision
      url: https://docs.magistrala.abstractmachines.fr/

paths:
  /{domainID}/mapping:
    post:
      summary: Adds new device to proxy
      description: Adds new device to proxy
      tags:
        - provision
      parameters:
        - $ref: "auth.yml#/components/parameters/DomainID"
      requestBody:
        $ref: "#/components/requestBodies/ProvisionReq"
      responses:
        "201":
          description: Created
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
    get:
      summary: Gets current mapping.
      description: Gets current mapping. This can be used in UI
        so that when bootstrap config is created from UI matches
        configuration created with provision service.
      tags:
        - provision
      parameters:
        - $ref: "auth.yml#/components/parameters/DomainID"
      responses:
        "200":
          $ref: "#/components/responses/ProvisionRes"
        "401":
          description: Missing or invalid access token provided.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "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:
  requestBodies:
    ProvisionReq:
      description: MAC address of device or other identifier
      content:
        application/json:
          schema:
            type: object
            required:
              - external_id
              - external_key
            properties:
              external_id:
                type: string
              external_key:
                type: string
              name:
                type: string

  responses:
    ServiceError:
      description: Unexpected server-side error occurred.
    ProvisionRes:
      description: Current mapping JSON representation.
      content:
        application/json:
          schema:
            type: object
    HealthRes:
      description: Service Health Check.
      content:
        application/health+json:
          schema:
            $ref: "./schemas/HealthInfo.yml"

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

security:
  - bearerAuth: []