magistrala/apidocs/openapi/notifiers.yaml

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

openapi: 3.0.1
info:
  title: Magistrala Notifiers service
  description: |
    HTTP API for Notifiers service.
    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:9014
  - url: https://localhost:9014
  - url: http://localhost:9015
  - url: https://localhost:9015

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

paths:
  /subscriptions:
    post:
      operationId: createSubscription
      summary: Create subscription
      description: Creates a new subscription give a topic and contact.
      tags:
        - notifiers
      requestBody:
        $ref: "#/components/requestBodies/Create"
      responses:
        "201":
          $ref: "#/components/responses/Create"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "409":
          description: Failed due to using an existing topic and contact.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
    get:
      operationId: listSubscriptions
      summary: List subscriptions
      description: List subscriptions given list parameters.
      tags:
        - notifiers
      parameters:
        - $ref: "#/components/parameters/Topic"
        - $ref: "#/components/parameters/Contact"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          $ref: "#/components/responses/Page"
        "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.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
  /subscriptions/{id}:
    get:
      operationId: viewSubscription
      summary: Get subscription with the provided id
      description: Retrieves a subscription with the provided id.
      tags:
        - notifiers
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          $ref: "#/components/responses/View"
        "400":
          description: Failed due to malformed ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
    delete:
      operationId: removeSubscription
      summary: Delete subscription with the provided id
      description: Removes a subscription with the provided id.
      tags:
        - notifiers
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "204":
          description: Subscription removed
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "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:
  schemas:
    Subscription:
      type: object
      properties:
        id:
          type: string
          format: ulid
          example: 01EWDVKBQSG80B6PQRS9PAAY35
          description: ULID id of the subscription.
        owner_id:
          type: string
          format: uuid
          example: 18167738-f7a8-4e96-a123-58c3cd14de3a
          description: An id of the owner who created subscription.
        topic:
          type: string
          example: topic/subtopic
          description: Topic to which the user subscribes.
        contact:
          type: string
          example: user@example.com
          description: The contact of the user to which the notification will be sent.
    CreateSubscription:
      type: object
      properties:
        topic:
          type: string
          example: topic/subtopic
          description: Topic to which the user subscribes.
        contact:
          type: string
          example: user@example.com
          description: The contact of the user to which the notification will be sent.
    Page:
      type: object
      properties:
        subscriptions:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Subscription"
        total:
          type: integer
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.

  parameters:
    Id:
      name: id
      description: Unique identifier.
      in: path
      schema:
        type: string
        format: ulid
      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
    Topic:
      name: topic
      description: Topic name.
      in: query
      schema:
        type: string
      required: false
    Contact:
      name: contact
      description: Subscription contact.
      in: query
      schema:
        type: string
      required: false

  requestBodies:
    Create:
      description: JSON-formatted document describing the new subscription to be created
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateSubscription"

  responses:
    Create:
      description: Created a new subscription.
      headers:
        Location:
          content:
            text/plain:
              schema:
                type: string
                description: Created subscription relative URL
                example: /subscriptions/{id}
    View:
      description: View subscription.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Subscription"
      links:
        delete:
          operationId: removeSubscription
          parameters:
            id: $response.body#/id
    Page:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Page"
    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>"

security:
  - bearerAuth: []