First draft of the consumption admin API specification

docs/api/streaming.openapi.yaml

+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: OSDU Streaming Service
+  license:
+    name: Apache 2.0
+    url: "http://www.apache.org/licenses/LICENSE-2.0"
+servers:
+  - url: "https://localhost:8080/api/streaming/v1"
+tags:
+  - name: streaming-consumption-api
+    description: Consumption API
+paths:
+  /consume/streams:
+    get:
+      summary: "List all registered consumption streams"
+      operationId: listAllStreams
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/StreamRecord"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /consume/stream:
+    post:
+      summary: "Register a new consumption stream"
+      operationId: createNewStream
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StreamDefinition"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                type: string
+                description: "ID of the stream created"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /consume/stream/{id}:
+    get:
+      summary: "Get stream definition by Id"
+      operationId: getStreamById
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+        - name: id
+          in: path
+          description: "Stream ID"
+          required: true
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamRecord"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    delete:
+      summary: "Delete stream definition by Id and decommision all associated compute resources"
+      operationId: deleteStreamById
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+        - name: id
+          in: path
+          description: "Stream ID"
+          required: true
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Stream deleted
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /consume/stream/{id}/start:
+    get:
+      summary: "Start live streaming for the specified stream Id"
+      operationId: startStreamById
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+        - name: id
+          in: path
+          description: "Stream ID"
+          required: true
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Start command performed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamStatus"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /consume/stream/{id}/stop:
+    get:
+      summary: "Stop live streaming for the specified stream Id"
+      operationId: stopStreamById
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+        - name: id
+          in: path
+          description: "Stream ID"
+          required: true
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Stop command performed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamStatus"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /consume/stream/{id}/info:
+    get:
+      summary: "Get the current status of the stream by Id"
+      operationId: getStreamStatusById
+      tags:
+        - streaming-consumption-api
+      parameters:
+        - name: data-partition-id
+          in: header
+          description: "tenant"
+          required: true
+          example: "opendes"
+          schema:
+            type: string
+        - name: id
+          in: path
+          description: "Stream ID"
+          required: true
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Info command performed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamStatus"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+components:
+  schemas:
+    StreamRecord:
+      type: object
+      required:
+        - id
+        - kind
+        - data
+        - acl
+        - legal
+        - type
+        - namespace
+      properties:
+        id:
+          type: string
+          pattern: '^[\\w\\-\\.]+:dataset\\-\\-Stream.Kafka:[\\w\\-\\.\\:\\%]+'
+          example: "opendes:dataset--Stream.Kafka:4dc4e8ec354e4953b6968fcb1d9d9f38"
+          description: "Unique identifier in whole Data Ecosystem. When not provided, Data Ecosystem will create and assign an id to the record."
+        kind:
+          type: string
+          example: "osdu:wks:dataset--Stream.Kafka:1.0.0"
+          description: "Record kind for which the schema information is applied to."
+        data:
+          $ref: "#/components/schemas/StreamDataset"
+        namespace:
+          type: string
+          example: "opendes:osdu"
+        version:
+          type: integer
+          format: int64
+          example: 1605804087572060
+        acl:
+          $ref: "#/components/schemas/Acl"
+        legal:
+          $ref: "#/components/schemas/Legal"
+        meta:
+          type: array
+          items:
+            $ref: "#/components/schemas/Map"
+        ancestry:
+          $ref: "#/components/schemas/RecordAncestry"
+    StreamDataset:
+      type: object
+      properties:
+        ResourceSecurityClassification:
+          type: string
+          example: "opendes:reference-data--ResourceSecurityClassification:RESTRICTED:"
+        ResourceSource:
+          type: string
+          example: "Contoso Inc."
+        DatasetProperties:
+          type: object
+          properties:
+            StreamType:
+              type: string
+              example: "opendes:reference-data--StreamType:FOLLOW:"
+            StreamDirection:
+              type: string
+              example: "opendes:reference-data--StreamDirection:CONSUME:"
+            StreamDefinition:
+              $ref: "#/components/schemas/StreamDefinition"
+    StreamDefinition:
+      type: object
+      required:
+        - SubscribeIDs
+        - Description
+      properties:
+        SourceTopics:
+          type: array
+          items:
+            type: string
+            example: "opendes_wks_work-product-component--WellLog_1.0.0"
+        SinkTopics:
+          type: array
+          items:
+            type: string
+            example: "opendes_4dc4e8ec354e4953b6968fcb1d9d9f38_work-product-component--WellLog_1.0.0"
+        SubscribeIDs:
+          type: array
+          items:
+            type: string
+            example: "opendes:work-product-component--WellLog:be54a691c0384182944d71c6b2b6f699"
+        Filter:
+          type: string
+          example: "TBD"
+        Aggregate:
+          type: string
+          example: "TBD"
+        Description:
+          type: string
+          example: "This stream provides live unmodified well log data for app 1"
+    StreamStatus:
+      type: object
+      properties:
+        Command:
+          type: string
+          enum:
+            - start
+            - stop
+            - info
+        Workers:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              state:
+                type: string
+                enum:
+                  - running
+                  - stopped
+                  - failed
+    Acl:
+      type: object
+      properties:
+        owners:
+          type: array
+          items:
+            type: string
+            example: "data.stream-4dc4e8ec354e4953b6968fcb1d9d9f38.producer@opendes.contoso.com"
+        viewers:
+          type: array
+          items:
+            type: string
+            example: "data.stream-4dc4e8ec354e4953b6968fcb1d9d9f38.consumer@opendes.contoso.com"
+    Legal:
+      type: object
+      properties:
+        legaltags:
+          type: array
+          items:
+            type: string
+            example: "opendes-public-usa-dataset"
+        otherRelevantDataCountries:
+          type: array
+          items:
+            type: string
+            example: "US"
+        status:
+          type: string
+          enum:
+            - compliant
+            - incompliant
+    Map:
+      type: object
+      additionalProperties:
+        type: object
+    RecordAncestry:
+      type: object
+      properties:
+        parents:
+          type: array
+          items:
+            type: string
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+security:
+  - JWT:
+      - global