enrichment-coordinator-service/api/ecs-api.yaml

openapi: 3.0.1
info:
  title: Data management and exposure
  description: <h1>API documentation</h1><h2>General</h2><p>  The service is mainly
    a broker between data producers and data consumers. A data producer has the ability
    to produce one or several types of data (Information Type). One type of data can
    be produced by zero to many producers. <br /><br />A data consumer can have several
    active data subscriptions (Information Job). One Information Job consists of the
    type of data to produce and additional parameters for filtering of the data. These
    parameters are different for different data types.</p><h2>APIs provided by the
    service</h2><h4>A1-EI</h4><p>  This API is between Near-RT RIC and the Non-RT
    RIC.  The Near-RT RIC is a data consumer, which creates Information Jobs to subscribe
    for data.  In this context, the information is referred to as 'Enrichment Information',
    EI.</p><h4>Data producer API</h4><p>  This API is provided by the Non-RT RIC platform
    and is intended to be part of the O-RAN R1 interface.  The API is for use by different
    kinds of data producers and provides support for:<ul><li>Registry of supported
    information types and which parameters needed to setup a subscription.</li><li>Registry
    of existing data producers.</li><li>Callback API provided by producers to setup
    subscriptions.</li></ul></p><h4>Data consumer API</h4><p>  This API is provided
    by the Non-RT RIC platform and is intended to be part of the O-RAN R1 interface.  The
    API is for use by different kinds of data consumers and provides support for:<ul><li>Querying
    of available types of data to consume.</li><li>Management of data subscription
    jobs</li></ul></p><h4>Service status</h4><p>  This API provides a means to monitor
    the health of this service.</p>
  license:
    name: Copyright (C) 2020 Nordix Foundation. Licensed under the Apache License.
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: "1.0"
servers:
- url: /
tags:
- name: A1-EI (registration)
  description: Data consumer EI job registration
- name: A1-EI (callbacks)
  description: Data consumer EI job status callbacks
- name: Data producer (callbacks)
  description: API implemented by data producers
- name: Data producer (registration)
  description: API for data producers
- name: Service status
  description: API for monitoring of the service
- name: Data consumer
  description: API for data consumers
paths:
  /data-producer/v1/info-types:
    get:
      tags:
      - Data producer (registration)
      summary: Info Type identifiers
      operationId: getInfoTypdentifiers
      responses:
        200:
          description: Info Type identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /A1-EI/v1/eitypes/{eiTypeId}:
    get:
      tags:
      - A1-EI (registration)
      summary: Individual EI type
      operationId: getEiType
      parameters:
      - name: eiTypeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: EI type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EiTypeObject'
        404:
          description: Enrichment Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-producer/v1/info-types/{infoTypeId}:
    get:
      tags:
      - Data producer (registration)
      summary: Individual Information Type
      operationId: getInfoType
      parameters:
      - name: infoTypeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Info Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/producer_info_type_info'
        404:
          description: Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Data producer (registration)
      summary: Individual Information Type
      operationId: putInfoType
      parameters:
      - name: infoTypeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/producer_info_type_info'
        required: true
      responses:
        200:
          description: Type updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        201:
          description: Type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Data producer (registration)
      summary: Individual Information Type
      operationId: deleteInfoType
      parameters:
      - name: infoTypeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        204:
          description: Producer deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        406:
          description: The Information type has one or several active producers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /A1-EI/v1/eitypes:
    get:
      tags:
      - A1-EI (registration)
      summary: EI type identifiers
      operationId: getEiTypeIdentifiers
      responses:
        200:
          description: EI type identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /data-consumer/v1/info-types:
    get:
      tags:
      - Data consumer
      summary: Information type identifiers
      operationId: getinfoTypeIdentifiers
      responses:
        200:
          description: Information type identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /data-producer/v1/info-producers/{infoProducerId}:
    get:
      tags:
      - Data producer (registration)
      summary: Individual Information Producer
      operationId: getInfoProducer
      parameters:
      - name: infoProducerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information producer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/producer_registration_info'
        404:
          description: Information producer is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Data producer (registration)
      summary: Individual Information Producer
      operationId: putInfoProducer
      parameters:
      - name: infoProducerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/producer_registration_info'
        required: true
      responses:
        200:
          description: Producer updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        201:
          description: Producer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Producer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Data producer (registration)
      summary: Individual Information Producer
      operationId: deleteInfoProducer
      parameters:
      - name: infoProducerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        204:
          description: Producer deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Producer is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /producer_simulator/info_job/{infoJobId}:
    delete:
      tags:
      - Data producer (callbacks)
      summary: Callback for Information Job deletion
      description: The call is invoked to terminate a data subscription. The endpoint
        is provided by the Information Producer.
      operationId: jobDeletedCallback
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
  /status:
    get:
      tags:
      - Service status
      summary: Returns status and statistics of this service
      operationId: getStatus
      responses:
        200:
          description: Service is living
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status_info'
  /A1-EI/v1/eijobs/{eiJobId}:
    get:
      tags:
      - A1-EI (registration)
      summary: Individual EI job
      operationId: getIndividualEiJob_1
      parameters:
      - name: eiJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: EI job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EiJobObject'
        404:
          description: Enrichment Information job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - A1-EI (registration)
      summary: Individual EI job
      operationId: putIndividualEiJob
      parameters:
      - name: eiJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EiJobObject'
        required: true
      responses:
        200:
          description: Job updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        201:
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Enrichment Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - A1-EI (registration)
      summary: Individual EI job
      operationId: deleteIndividualEiJob_1
      parameters:
      - name: eiJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        204:
          description: Job deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Enrichment Information job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /producer_simulator/health_check:
    get:
      tags:
      - Data producer (callbacks)
      summary: Producer supervision
      description: The endpoint is provided by the Information Producer and is used
        for supervision of the producer.
      operationId: producerSupervision
      responses:
        200:
          description: The producer is OK
          content:
            application/json:
              schema:
                type: string
  /data-consumer/v1/info-jobs:
    get:
      tags:
      - Data consumer
      summary: Information Job identifiers
      description: query for information job identifiers
      operationId: getJobIds
      parameters:
      - name: infoTypeId
        in: query
        description: selects subscription jobs of matching information type
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: owner
        in: query
        description: selects subscription jobs for one job owner
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Information information job identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        404:
          description: Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-consumer/v1/info-jobs/{infoJobId}:
    get:
      tags:
      - Data consumer
      summary: Individual data subscription job
      operationId: getIndividualEiJob
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information subscription job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consumer_job'
        404:
          description: Information subscription job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Data consumer
      summary: Individual data subscription job
      description: The job will be enabled when a producer is available
      operationId: putIndividualInfoJob
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: typeCheck
        in: query
        description: when true, a validation of that the type exists and that the
          job matches the type schema.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/consumer_job'
        required: true
      responses:
        200:
          description: Job updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        201:
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Data consumer
      summary: Individual data subscription job
      operationId: deleteIndividualEiJob
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        204:
          description: Job deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        404:
          description: Information subscription job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-producer/v1/info-producers:
    get:
      tags:
      - Data producer (registration)
      summary: Information producer identifiers
      operationId: getInfoProducerIdentifiers
      parameters:
      - name: info_type_id
        in: query
        description: If given, only the producers for the EI Data type is returned.
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Information producer identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /data-consumer/v1/info-types/{infoTypeId}:
    get:
      tags:
      - Data consumer
      summary: Individual information type
      operationId: getInfoType_1
      parameters:
      - name: infoTypeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consumer_information_type'
        404:
          description: Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /producer_simulator/info_job:
    post:
      tags:
      - Data producer (callbacks)
      summary: Callback for Information Job creation/modification
      description: The call is invoked to activate or to modify a data subscription.
        The endpoint is provided by the Information Producer.
      operationId: jobCreatedCallback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/producer_info_job_request'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
  /example_dataconsumer/info_jobs/{infoJobId}/status:
    post:
      tags:
      - A1-EI (callbacks)
      summary: Callback for changed Information Job status
      description: The primitive is implemented by the data consumer and is invoked
        when a Information Job status has been changed.
      operationId: jobStatusCallback
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EiJobStatusObject'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
  /A1-EI/v1/eijobs:
    get:
      tags:
      - A1-EI (registration)
      summary: EI job identifiers
      description: query for EI job identifiers
      operationId: getEiJobIds
      parameters:
      - name: eiTypeId
        in: query
        description: selects EI jobs of matching EI type
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: owner
        in: query
        description: selects EI jobs for one EI job owner
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: EI job identifiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        404:
          description: Enrichment Information type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /A1-EI/v1/eijobs/{eiJobId}/status:
    get:
      tags:
      - A1-EI (registration)
      summary: EI job status
      operationId: getEiJobStatus_1
      parameters:
      - name: eiJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: EI job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EiJobStatusObject'
        404:
          description: Enrichment Information job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-producer/v1/info-producers/{infoProducerId}/status:
    get:
      tags:
      - Data producer (registration)
      summary: Information producer status
      operationId: getInfoProducerStatus
      parameters:
      - name: infoProducerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information producer status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/producer_status'
        404:
          description: Information producer is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-producer/v1/info-producers/{infoProducerId}/info-jobs:
    get:
      tags:
      - Data producer (registration)
      summary: Information Job definitions
      description: Information Job definitions for one Information Producer
      operationId: getInfoProducerJobs
      parameters:
      - name: infoProducerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information producer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/producer_info_job_request'
        404:
          description: Information producer is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /data-consumer/v1/info-jobs/{infoJobId}/status:
    get:
      tags:
      - Data consumer
      summary: Job status
      operationId: getEiJobStatus
      parameters:
      - name: infoJobId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Information subscription job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consumer_job_status'
        404:
          description: Information subscription job is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    consumer_information_type:
      required:
      - job_data_schema
      type: object
      properties:
        job_data_schema:
          type: object
          description: Json schema for the job data
      description: Information for an Information type
    EiTypeObject:
      type: object
      description: Information for an EI type
    status_info:
      required:
      - no_of_jobs
      - no_of_producers
      - no_of_types
      - status
      type: object
      properties:
        no_of_producers:
          type: integer
          description: Number of Information Producers
          format: int32
        no_of_types:
          type: integer
          description: Number of Information Types
          format: int32
        no_of_jobs:
          type: integer
          description: Number of Information Jobs
          format: int32
        status:
          type: string
          description: status text
    producer_registration_info:
      required:
      - info_job_callback_url
      - info_producer_supervision_callback_url
      - supported_info_types
      type: object
      properties:
        info_producer_supervision_callback_url:
          type: string
          description: callback for producer supervision
        supported_info_types:
          type: array
          description: Supported Information Type IDs
          items:
            type: string
            description: Supported Information Type IDs
        info_job_callback_url:
          type: string
          description: callback for Information Job
      description: Information for an Information Producer
    ProblemDetails:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of
            the problem.
          example: Information Job type not found
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this
            occurrence of the problem.
          format: int32
          example: 404
      description: A problem detail to carry details in a HTTP response according
        to RFC 7807
    EiJobStatusObject:
      required:
      - eiJobStatus
      type: object
      properties:
        eiJobStatus:
          type: string
          description: Allowed values for EI job status
          enum:
          - ENABLED
          - DISABLED
      description: Status for an EI job
    consumer_job_status:
      required:
      - info_job_status
      type: object
      properties:
        info_job_status:
          type: string
          description: Allowed values for Information Job status
          enum:
          - ENABLED
          - DISABLED
      description: Status for an Information Job
    EiJobObject:
      required:
      - eiTypeId
      - jobDefinition
      - jobOwner
      - jobResultUri
      type: object
      properties:
        eiTypeId:
          type: string
          description: EI type Idenitifier of the EI job
        jobResultUri:
          type: string
          description: The target URI of the EI data
        jobOwner:
          type: string
          description: Identity of the owner of the job
        statusNotificationUri:
          type: string
          description: The target of EI job status notifications
        jobDefinition:
          type: object
          description: EI type specific job data
      description: Information for an Enrichment Information Job
    producer_info_type_info:
      required:
      - info_job_data_schema
      type: object
      properties:
        info_job_data_schema:
          type: object
          description: Json schema for the job data
      description: Information for an Information Type
    producer_info_job_request:
      required:
      - info_job_identity
      type: object
      properties:
        owner:
          type: string
          description: The owner of the job
        last_updated:
          type: string
          description: The time when the job was last updated or created (ISO-8601)
        info_job_identity:
          type: string
          description: Identity of the Information Job
        target_uri:
          type: string
          description: URI for the target of the produced Information
        info_job_data:
          type: object
          description: Json for the job data
        info_type_identity:
          type: string
          description: Type identity for the job
      description: The body of the Information Producer callbacks for Information
        Job creation and deletion
    consumer_job:
      required:
      - info_type_id
      - job_definition
      - job_owner
      - job_result_uri
      type: object
      properties:
        info_type_id:
          type: string
          description: Information type Idenitifier of the subscription job
        job_result_uri:
          type: string
          description: The target URI of the subscribed information
        job_owner:
          type: string
          description: Identity of the owner of the job
        job_definition:
          type: object
          description: Information type specific job data
        status_notification_uri:
          type: string
          description: The target of Information subscription job status notifications
      description: Information for an Enrichment  Information Job
    producer_status:
      required:
      - operational_state
      type: object
      properties:
        operational_state:
          type: string
          description: Represents the operational states
          enum:
          - ENABLED
          - DISABLED
      description: Status for an Info Producer
    Void:
      type: object
      description: 'Void/empty '