path: root/a1-policy-management/api/pms-api.yaml

openapi: 3.0.1
info:
  title: A1 Policy Management Service
  description: <h2>General</h2><p>The O-RAN Non-RT RIC Policy Management Service provides
    a REST API for management of A1 policies. <br/>The main tasks of the service are:</p><ul><li>A1
    Policy creation, modification and deletion.</li><li>Monitoring and maintaining
    consistency of the SMO view of A1 policies and the Near-RT RICs</li><li>Maintaining
    a view of supported Near-RT RIC policy types</li><li>Supervision of using services
    (R-APPs). When a service is unavailable, its policies are removed.</li></ul><h2>APIs
    provided by the service</h2><h3>A1 Policy Management</h3><p>This is an API for
    management of A1 Policies.</p><ul><li>A1 Policy retrieval, creation, modification
    and deletion.</li><li>Retrieval of supported A1 Policy types for a Near-RT RIC</li><li>Retrieval
    of status for existing A1 policies</li></ul><h3>Management of configuration</h3><p>API
    for updating and retrieval of the component configuration. Note that there other
    ways to maintain the configuration.</p><h3>Callbacks</h3><p>These are endpoints
    that are invoked by this service. The callbacks are registered in this service
    at service registration.</p><h3>NearRT-RIC Repository</h3><p>This is an API that
    provides support for looking up a NearRT-RIC. Each A1 policy is targeted for one
    Near-RT RIC.</p><h3>Health Check</h3><p>API used for supervision of the PMS component.</p><h3>Service
    Registry and Supervision</h3><p>API used for registering services that uses PMS.
    Each A1 policy is optionally owned by a service. PMS can supervise each registered
    service by a heart-beat supervision and will automatically remove policies for
    unavailable services. Note that a service does not need to be registered in order
    to create A1 Policies. This is a feature that is optional to use.</p><h3>Spring
    Boot Actuator</h3><p>Provides generic functions  used to monitor and manage the
    Spring web application.</p>
  license:
    name: Copyright (C) 2020-2023 Nordix Foundation. Licensed under the Apache License.
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 1.1.0
servers:
- url: /
tags:
- name: Service Registry and Supervision
- name: A1 Policy Management
- name: NearRT-RIC Repository
- name: Callbacks
- name: Health Check
- name: Actuator
  description: Monitor and interact
  externalDocs:
    description: Spring Boot Actuator Web API Documentation
    url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
- name: Management of configuration
paths:
  /a1-policy/v2/policy-instances:
    get:
      tags:
      - A1 Policy Management
      summary: Query for A1 policy instances
      description: Returns a list of A1 policies matching given search criteria. <br>If
        several query parameters are defined, the policies matching all conditions
        are returned.
      operationId: getPolicyInstances
      parameters:
      - name: policytype_id
        in: query
        description: Select policies with a given type identity.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: ric_id
        in: query
        description: Select policies for a given Near-RT RIC identity.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: service_id
        in: query
        description: Select policies owned by a given service.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: type_name
        in: query
        description: Select policies of a given type name (type identity has the format
          <typename_version>)
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Policies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy_info_list_v2'
        404:
          description: Near-RT RIC, policy type or service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/threaddump:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'threaddump'
      operationId: threaddump_2
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/status:
    get:
      tags:
      - Health Check
      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_v2'
  /actuator/loggers:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'loggers'
      operationId: loggers
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /actuator/health/**:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'health-path'
      operationId: health-path
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/rics/ric:
    get:
      tags:
      - NearRT-RIC Repository
      summary: Returns info for one Near-RT RIC
      description: Either a Near-RT RIC identity or a Managed Element identity can
        be specified.<br>The intention with Managed Element identity is the ID used
        in O1 for accessing the traffical element (such as the ID of CU).
      operationId: getRic
      parameters:
      - name: managed_element_id
        in: query
        description: The identity of a Managed Element. If given, the Near-RT RIC
          managing the ME is returned.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: ric_id
        in: query
        description: The identity of a Near-RT RIC to get information for.
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Near-RT RIC is found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ric_info_v2'
        404:
          description: Near-RT RIC is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/shutdown:
    post:
      tags:
      - Actuator
      summary: Actuator web endpoint 'shutdown'
      operationId: shutdown
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/policy-types:
    get:
      tags:
      - A1 Policy Management
      summary: Query policy type identities
      operationId: getPolicyTypes
      parameters:
      - name: ric_id
        in: query
        description: Select types for the given Near-RT RIC identity.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: type_name
        in: query
        description: Select types with the given type name (type identity has the
          format <typename_version>)
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: compatible_with_version
        in: query
        description: Select types that are compatible with the given version. This
          parameter is only applicable in conjunction with type_name. As an example
          version 1.9.1 is compatible with 1.0.0 but not the other way around. Matching
          types will be returned sorted in ascending order.
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Policy type IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policytype_id_list_v2'
        404:
          description: Near-RT RIC is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
  /a1-policy/v2/policies/{policy_id}:
    get:
      tags:
      - A1 Policy Management
      summary: Returns a policy
      operationId: getPolicy
      parameters:
      - name: policy_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Policy found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy_info_v2'
        404:
          description: Policy is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
    delete:
      tags:
      - A1 Policy Management
      summary: Delete a policy
      operationId: deletePolicy
      parameters:
      - name: policy_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/void'
        423:
          description: Near-RT RIC is not operational
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
        204:
          description: Policy deleted
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/void'
        404:
          description: Policy is not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/metrics/{requiredMetricName}:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'metrics-requiredMetricName'
      operationId: metrics-requiredMetricName
      parameters:
      - name: requiredMetricName
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/configuration:
    get:
      tags:
      - Management of configuration
      summary: Returns the contents of the application configuration file
      operationId: getConfiguration
      responses:
        200:
          description: Configuration
          content:
            application/json:
              schema:
                type: object
        404:
          description: File is not found or readable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
    put:
      tags:
      - Management of configuration
      summary: Replace the current configuration file with the given configuration
      operationId: putConfiguration
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: Configuration updated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/void'
        400:
          description: Invalid configuration provided
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
        500:
          description: Something went wrong when replacing the configuration. Try
            again.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator:
    get:
      tags:
      - Actuator
      summary: Actuator root web endpoint
      operationId: links
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Link'
  /actuator/loggers/{name}:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'loggers-name'
      operationId: loggers-name_2
      parameters:
      - name: name
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
    post:
      tags:
      - Actuator
      summary: Actuator web endpoint 'loggers-name'
      operationId: loggers-name
      parameters:
      - name: name
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/services/{service_id}/keepalive:
    put:
      tags:
      - Service Registry and Supervision
      summary: Heartbeat indicates that the service is running
      description: A registered service should invoke this operation regularly to
        indicate that it is still alive. If a registered service fails to invoke this
        operation before the end of a timeout period the service will be deregistered
        and all its A1 policies wil be removed. (This timeout can be set or disabled
        when each service is initially registered)
      operationId: keepAliveService
      parameters:
      - name: service_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Service supervision timer refreshed, OK
          content:
            '*/*':
              schema:
                type: object
        404:
          description: The service is not found, needs re-registration
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/metrics:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'metrics'
      operationId: metrics
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/rics:
    get:
      tags:
      - NearRT-RIC Repository
      summary: Query Near-RT RIC information
      description: The call returns all Near-RT RICs that supports a given policy
        type identity
      operationId: getRics
      parameters:
      - name: policytype_id
        in: query
        description: The identity of a policy type. If given, all Near-RT RICs supporting
          the policy type are returned
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ric_info_list_v2'
        404:
          description: Policy type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
  /a1-policy/v2/services:
    get:
      tags:
      - Service Registry and Supervision
      summary: Returns service information
      description: Either information about a registered service with given identity
        or all registered services are returned.
      operationId: getServices
      parameters:
      - name: service_id
        in: query
        description: The identity of the service
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_list_v2'
        404:
          description: Service is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
    put:
      tags:
      - Service Registry and Supervision
      summary: Register a service
      description: Registering a service is needed to:<ul><li>Get callbacks about
        available NearRT RICs.</li><li>Activate supervision of the service. If a service
        is inactive, its policies will automatically be deleted.</li></ul>Policies
        can be created even if the service is not registerred. This is a feature which
        it is optional to use.
      operationId: putService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service_registration_info_v2'
        required: true
      responses:
        200:
          description: Service updated
          content:
            '*/*':
              schema:
                type: object
        201:
          description: Service created
          content:
            '*/*':
              schema:
                type: object
        400:
          description: The ServiceRegistrationInfo is not accepted
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/info:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'info'
      operationId: info
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /status:
    get:
      tags:
      - Health Check
      summary: Returns status and statistics of this service
      operationId: getStatusV1
      responses:
        200:
          description: Service is living
          content:
            '*/*':
              schema:
                type: string
  /a1-policy/v2/policy-types/{policytype_id}:
    get:
      tags:
      - A1 Policy Management
      summary: Returns a policy type definition
      operationId: getPolicyType
      parameters:
      - name: policytype_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Policy type
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/policytype_v2'
        404:
          description: Policy type is not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/logfile:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'logfile'
      operationId: logfile
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /actuator/health:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'health'
      operationId: health
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/policies:
    get:
      tags:
      - A1 Policy Management
      summary: Query policy identities
      description: Returns a list of A1 policies matching given search criteria. <br>If
        several query parameters are defined, the policies matching all conditions
        are returned.
      operationId: getPolicyIds
      parameters:
      - name: policytype_id
        in: query
        description: Select policies of a given policy type identity.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: ric_id
        in: query
        description: Select policies of a given Near-RT RIC identity.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: service_id
        in: query
        description: Select policies owned by a given service.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: type_name
        in: query
        description: Select policies of types with the given type name (type identity
          has the format <typename_version>)
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        200:
          description: Policy identities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy_id_list_v2'
        404:
          description: Near-RT RIC or type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
    put:
      tags:
      - A1 Policy Management
      summary: Create or update a policy
      operationId: putPolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/policy_info_v2'
        required: true
      responses:
        200:
          description: Policy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/void'
        201:
          description: Policy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/void'
        423:
          description: Near-RT RIC is not operational
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
        404:
          description: Near-RT RIC or policy type is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
  /r-app/near-rt-ric-status:
    post:
      tags:
      - Callbacks
      summary: Callback for Near-RT RIC status
      description: The URL to this call is registered at Service registration.
      operationId: serviceCallback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service_callback_info_v2'
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/void'
  /a1-policy/v2/services/{service_id}:
    delete:
      tags:
      - Service Registry and Supervision
      summary: Unregister a service
      operationId: deleteService
      parameters:
      - name: service_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Not used
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/void'
        204:
          description: Service unregistered
          content:
            '*/*':
              schema:
                type: object
        404:
          description: Service not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/error_information'
  /actuator/heapdump:
    get:
      tags:
      - Actuator
      summary: Actuator web endpoint 'heapdump'
      operationId: heapdump
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /a1-policy/v2/policies/{policy_id}/status:
    get:
      tags:
      - A1 Policy Management
      summary: Returns a policy status
      operationId: getPolicyStatus
      parameters:
      - name: policy_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: Policy status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/policy_status_info_v2'
        404:
          description: Policy is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_information'
components:
  schemas:
    error_information:
      type: object
      properties:
        detail:
          type: string
          description: ' A human-readable explanation specific to this occurrence
            of the problem.'
          example: Policy 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: Problem as defined in https://tools.ietf.org/html/rfc7807
    void:
      type: object
      description: Void/empty
    status_info_v2:
      type: object
      properties:
        status:
          type: string
          description: status text
    ric_info_v2:
      type: object
      properties:
        ric_id:
          type: string
          description: identity of the Near-RT RIC
        managed_element_ids:
          type: array
          description: O1 identities for managed entities
          items:
            type: string
            description: O1 identities for managed entities
        state:
          type: string
          description: Represents the states for a Near-RT RIC
          enum:
          - UNAVAILABLE
          - AVAILABLE
          - SYNCHRONIZING
          - CONSISTENCY_CHECK
        policytype_ids:
          type: array
          description: supported policy types
          items:
            type: string
            description: supported policy types
      description: Information for a Near-RT RIC
    service_registration_info_v2:
      required:
      - service_id
      type: object
      properties:
        callback_url:
          type: string
          description: callback for notifying of Near-RT RIC state changes
        service_id:
          type: string
          description: identity of the service
        keep_alive_interval_seconds:
          type: integer
          description: keep alive interval for the service. This is used to enable
            optional heartbeat supervision of the service. If set (> 0) the registered
            service should regularly invoke a 'keepalive' REST call. When a service
            fails to invoke this 'keepalive' call within the configured time, the
            service is considered unavailable. An unavailable service will be automatically
            deregistered and its policies will be deleted. Value 0 means timeout supervision
            is disabled.
          format: int64
      description: Information for one service
    policy_info_list_v2:
      type: object
      properties:
        policies:
          type: array
          description: List of policy information
          items:
            $ref: '#/components/schemas/policy_info_v2'
      description: List of policy information
    policy_status_info_v2:
      type: object
      properties:
        last_modified:
          type: string
          description: timestamp, last modification time
        status:
          type: object
          description: the Policy status
      description: Status for one A1-P Policy
    service_status_v2:
      type: object
      properties:
        callback_url:
          type: string
          description: callback for notifying of RIC synchronization
        service_id:
          type: string
          description: identity of the service
        keep_alive_interval_seconds:
          type: integer
          description: policy keep alive timeout
          format: int64
        time_since_last_activity_seconds:
          type: integer
          description: time since last invocation by the service
          format: int64
      description: List of service information
    ric_info_list_v2:
      type: object
      properties:
        rics:
          type: array
          description: List of Near-RT RIC information
          items:
            $ref: '#/components/schemas/ric_info_v2'
      description: List of Near-RT RIC information
    policytype_v2:
      type: object
      properties:
        policy_schema:
          type: object
          description: Policy type json schema. The schema is a json object following
            http://json-schema.org/draft-07/schema
      description: Policy type
    policytype_id_list_v2:
      type: object
      properties:
        policytype_ids:
          type: array
          description: Policy type identities
          items:
            type: string
            description: Policy type identities
      description: Information about policy types
    policy_info_v2:
      required:
      - policy_data
      - policy_id
      - policytype_id
      - ric_id
      type: object
      properties:
        ric_id:
          type: string
          description: identity of the target Near-RT RIC
        policy_id:
          type: string
          description: identity of the policy
        transient:
          type: boolean
          description: if true, the policy is deleted at RIC restart. If false, its
            value is maintained by this service until explicitly deleted. Default
            false.
          example: false
          default: false
        service_id:
          type: string
          description: the identity of the service owning the policy. This can be
            used to group the policies (it is possible to get all policies associated
            to a service). Note that the service does not need to be registerred.
        policy_data:
          type: object
          description: the configuration of the policy
        status_notification_uri:
          type: string
          description: Callback URI for policy status updates
        policytype_id:
          type: string
          description: identity of the policy type
      description: Information for one A1-P Policy
    policy_id_list_v2:
      type: object
      properties:
        policy_ids:
          type: array
          description: Policy identities
          items:
            type: string
            description: Policy identities
      description: A list of policy identities
    service_list_v2:
      type: object
      properties:
        service_list:
          type: array
          description: List of service information
          items:
            $ref: '#/components/schemas/service_status_v2'
      description: List of service information
    service_callback_info_v2:
      required:
      - event_type
      - ric_id
      type: object
      properties:
        ric_id:
          type: string
          description: identity of a Near-RT RIC
        event_type:
          type: string
          description: |-
            values:
            AVAILABLE: the  Near-RT RIC has become available for A1 Policy management
          enum:
          - AVAILABLE
      description: Information transferred as in Service callbacks (callback_url)
    Link:
      type: object
      properties:
        templated:
          type: boolean
        href:
          type: string