openapi: 3.0.1 info: title: A1 Policy Management Service description:

General

The O-RAN Non-RT RIC Policy Management Service provides a REST API for management of A1 policies.
The main tasks of the service are:

APIs provided by the service

A1 Policy Management

This is an API for management of A1 Policies.

Management of configuration

API for updating and retrieval of the component configuration. Note that there other ways to maintain the configuration.

Callbacks

These are endpoints that are invoked by this service. The callbacks are registered in this service at service registration.

NearRT-RIC Repository

This is an API that provides support for looking up a NearRT-RIC. Each A1 policy is targeted for one Near-RT RIC.

Health Check

API used for supervision of the PMS component.

Service Registry and Supervision

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.

Spring Boot Actuator

Provides generic functions used to monitor and manage the Spring web application.

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.
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 ) 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.
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 ) 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: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.
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 ) 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