OpenAPI specification for Beckn Network Observability

api/network-observability/README.md

@@ -0,0 +1,77 @@
+# How to build the specification
+
+The full specification can be found at `api/network-observability/build/network-observability.yaml`
+
+This is an autogenerated file created by compiling two sets of components namely,
+
+1. APIs : found at `api/network-observability/components/io`
+2. Schema : found at `api/network-observability/components/schemas`
+
+The compilation flow is illustrated below
+
+
+# Compilation steps
+
+## Step 1 : Create the schema index file
+
+- Go to the ```api/network-observability/components/schemas/``` folder
+- Create a file ```index.yaml```. If already present, open it in a text editor
+- It will contain a list of schema with $refs pointing to specific schema files in the current folder as shown below
+
+```
+Context:
+  $ref: "../../../../schema/Context.yaml"
+
+Ack:
+  $ref: "../../../../schema/Ack.yaml"
+
+Error:
+  $ref: "../../../../schema/Error.yaml"
+...
+```
+- Ensure that each file in the ```schemas``` folder has an entry in this file. If it is not present, it will not be compiled
+
+
+## Step 2 : Create the unresolved OpenAPI file
+
+- Go to the `api/network-observability/components/` folder
+- In this folder, create a file - `index.yaml`. If it is already present, open it in a text editor.
+- In the file, you will see the following
+
+```
+openapi: 3.1.0
+info:
+  title: Beckn Protocol Specification Network Observability APIs
+
+...
+
+```
+- As you can see, the ```index.yaml``` contains the unresolved Open API definitions with references to the APIs found in ```api/network-observability/components/io/```
+- Ensure each API definition in the ```api/network-observability/components/io/``` folder is referenced in this file. If it is not present, it will not be compiled. 
+- Once all API referencing is done, save this file and close it.
+
+## Install swagger CLI
+
+- Install the swagger command line tool using ```npm```
+- Note: you may need to use root privileges if installing it globally
+
+```
+sudo npm install -g swagger-cli
+```
+
+## Generate the resolved OpenAPI definition file
+
+- Go to the root directory of this project i.e ```protocol-specifications/```
+- Run the following command
+
+```
+swagger-cli bundle api/network-observability/components/index.yaml --outfile api/network-observability/build/network-observability.yaml --type yaml
+```
+
+- If the command runs successfully, you should see an output like this,
+
+```
+Created api/network-observability/build/network-observability.yaml from api/network-observability/components/index.yaml
+```
+
+- Commit the changes and push the updated code

api/network-observability/components/index.yaml

@@ -0,0 +1,31 @@
+openapi: 3.1.0
+info:
+  title: Beckn Protocol Specification Network Observability APIs
+  description: This document contains the network observability API endpoints that are implemented by the observability platform.
+  version: "1.0.0"  
+security:
+  - SubscriberAuth: []
+paths:
+  /observe:
+    post:
+      tags:
+        - Beckn Observability Platform (BOP)
+      description: BAP and BPP push logs of transactions to BOP.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "./io/Observe.yaml"
+      responses:
+        default:
+          $ref: "./io/Response.yaml"
+components:
+  securitySchemes:
+    SubscriberAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: 'Signature of message body using signing public key of the caller. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
+  schemas:
+    $ref: "./schema/index.yaml"
+

api/network-observability/components/io/Observe.yaml

@@ -0,0 +1,16 @@
+type: object
+properties:
+  context:
+    allOf:
+      - $ref: "../../../../schema/Context.yaml"
+      - properties:
+          action:
+            enum:
+              - observe
+        required:
+          - action
+  message:
+    $ref: "../schema/LogEntry.yaml"
+required:
+  - context
+  - message

api/network-observability/components/io/Response.yaml

@@ -0,0 +1,18 @@
+description: Acknowledgement of message received after successful validation of schema and signature
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        message:
+          type: object
+          properties:
+            ack:
+              allOf:
+                - $ref: "../../../../schema/Ack.yaml"
+          required:
+            - ack
+        error:
+          $ref: "../../../../schema/Error.yaml"
+      required:
+        - message

api/network-observability/components/schema/LogEntry.yaml

@@ -0,0 +1,8 @@
+description: An instance of an entry in the Observability Platform.
+type: object
+properties:
+  type:
+    $ref: './TransactionType.yaml'
+  data:
+    type: object
+    description: Payload corresponding to the Beckn message type (request or response). PII must be anonymized by the sender.

api/network-observability/components/schema/TransactionType.yaml

@@ -0,0 +1,53 @@
+description: Type of transaction log pushed to the observability platform. i.e, init, confirm, on_init etc
+type: string
+enum:
+  - on_search
+  - select
+  - on_select
+  - init
+  - on_init
+  - confirm
+  - on_confirm
+  - status
+  - on_status
+  - update
+  - on_update
+  - track
+  - on_track
+  - cancel
+  - on_cancel
+  - support
+  - on_support
+  - rating
+  - on_rating
+  - get_rating_categories
+  - rating_categories
+  - get_cancellation_reasons
+  - cancellation_reasons
+  - get_return_reasons
+  - return_reasons
+  - on_search_response
+  - select_response
+  - on_select_response
+  - init_response
+  - on_init_response
+  - confirm_response
+  - on_confirm_response
+  - status_response
+  - on_status_response
+  - update_response
+  - on_update_response
+  - track_response
+  - on_track_response
+  - cancel_response
+  - on_cancel_response
+  - support_response
+  - on_support_response
+  - rating_response
+  - on_rating_response
+  - get_rating_categories_response
+  - rating_categories_response
+  - get_cancellation_reasons_response
+  - cancellation_reasons_response
+  - get_return_reasons_response
+  - return_reasons_response

api/network-observability/components/schema/index.yaml

@@ -0,0 +1,23 @@
+Context:
+  $ref: "../../../../schema/Context.yaml"
+
+Ack:
+  $ref: "../../../../schema/Ack.yaml"
+
+Error:
+  $ref: "../../../../schema/Error.yaml"
+
+Descriptor:
+  $ref: "../../../../schema/Descriptor.yaml"
+
+Gps:
+  $ref: "../../../../schema/Gps.yaml"
+
+Scalar:
+  $ref: "../../../../schema/Scalar.yaml"
+
+LogEntry:
+  $ref: "./LogEntry.yaml"
+
+TransactionType:
+  $ref: "./TransactionType.yaml"