Update tools and API docs

Signed-off-by: Dusan Borovcanin <[email protected]>
absmach · Jul 11, 2024 · 5fe611b · 5fe611b
1 parent da5b497
commit 5fe611b
Show file tree

Hide file tree

Showing 87 changed files with 3,680 additions and 6,347 deletions.
diff --git a/Makefile b/Makefile
@@ -4,8 +4,7 @@
 MG_DOCKER_IMAGE_NAME_PREFIX ?= magistrala
 BUILD_DIR = build
 SERVICES = opcua lora influxdb-writer influxdb-reader mongodb-writer \
-	mongodb-reader cassandra-writer cassandra-reader postgres-writer postgres-reader \
-	timescale-writer timescale-reader twins provision certs smtp-notifier smpp-notifier
+	mongodb-reader cassandra-writer cassandra-reader twins smtp-notifier smpp-notifier
 TEST_API_SERVICES = certs notifiers provision readers twins
 TEST_API = $(addprefix test_api_,$(TEST_API_SERVICES))
 DOCKERS = $(addprefix docker_,$(SERVICES))

diff --git a/api/openapi/notifiers.yml b/api/openapi/notifiers.yml
@@ -0,0 +1,291 @@
+# 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: [email protected]
+  license:
+    name: Apache 2.0
+    url: https://github.com/absmach/magistrala/blob/main/LICENSE
+  version: 0.14.0
+
+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://docs.magistrala.abstractmachines.fr/
+
+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
+      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: [email protected]
+          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: [email protected]
+          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/HealthInfo.yml"
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        * Users access: "Authorization: Bearer <user_token>"
+
+security:
+  - bearerAuth: []