openapi: 3.0.1
info:
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:
- A1 Policy creation, modification and deletion.
- Monitoring\
\ and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs
- Maintaining\
\ a view of supported Near-RT RIC policy types
- Supervision of using services\
\ (R-APPs). When a service is unavailable, its policies are removed.
APIs\
\ provided by the service
A1 Policy Management
This is an API for\
\ management of A1 Policies.
- A1 Policy retrieval, creation, modification\
\ and deletion.
- Retrieval of supported A1 Policy types for a Near-RT RIC
- Retrieval\
\ of status for existing 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
title: A1 Policy Management Service
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
- 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: Actuator
- name: Management of configuration
paths:
/a1-policy/v2/policy-instances:
get:
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:
- description: Select policies with a given type identity.
explode: true
in: query
name: policytype_id
required: false
schema:
type: string
style: form
- description: Select policies for a given Near-RT RIC identity.
explode: true
in: query
name: ric_id
required: false
schema:
type: string
style: form
- description: Select policies owned by a given service.
explode: true
in: query
name: service_id
required: false
schema:
type: string
style: form
- description: Select policies of a given type name (type identity has the format
)
explode: true
in: query
name: type_name
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/policy_info_list_v2'
description: Policies
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: "Near-RT RIC, policy type or service not found"
summary: Query for A1 policy instances
tags:
- A1 Policy Management
/actuator/threaddump:
get:
operationId: threaddump_2
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'threaddump'
tags:
- Actuator
/a1-policy/v2/status:
get:
operationId: getStatus
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/status_info_v2'
description: Service is living
summary: Returns status and statistics of this service
tags:
- Health Check
/actuator/loggers:
get:
operationId: loggers
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'loggers'
tags:
- Actuator
/actuator/health/**:
get:
operationId: health-path
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'health-path'
tags:
- Actuator
/a1-policy/v2/rics/ric:
get:
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:
- description: "The identity of a Managed Element. If given, the Near-RT RIC\
\ managing the ME is returned."
explode: true
in: query
name: managed_element_id
required: false
schema:
type: string
style: form
- description: The identity of a Near-RT RIC to get information for.
explode: true
in: query
name: ric_id
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ric_info_v2'
description: Near-RT RIC is found
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC is not found
summary: Returns info for one Near-RT RIC
tags:
- NearRT-RIC Repository
/actuator/shutdown:
post:
operationId: shutdown
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'shutdown'
tags:
- Actuator
/a1-policy/v2/policy-types:
get:
operationId: getPolicyTypes
parameters:
- description: Select types for the given Near-RT RIC identity.
explode: true
in: query
name: ric_id
required: false
schema:
type: string
style: form
- description: Select types with the given type name (type identity has the
format )
explode: true
in: query
name: type_name
required: false
schema:
type: string
style: form
- 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.
explode: true
in: query
name: compatible_with_version
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/policytype_id_list_v2'
description: Policy type IDs
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC is not found
summary: Query policy type identities
tags:
- A1 Policy Management
/a1-policy/v2/policies/{policy_id}:
delete:
operationId: deletePolicy
parameters:
- explode: false
in: path
name: policy_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
$ref: '#/components/schemas/void'
description: Not used
"423":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC is not operational
"204":
content:
'*/*':
schema:
$ref: '#/components/schemas/void'
description: Policy deleted
"404":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Policy is not found
summary: Delete a policy
tags:
- A1 Policy Management
get:
operationId: getPolicy
parameters:
- explode: false
in: path
name: policy_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/policy_info_v2'
description: Policy found
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Policy is not found
summary: Returns a policy
tags:
- A1 Policy Management
/actuator/metrics/{requiredMetricName}:
get:
operationId: metrics-requiredMetricName
parameters:
- explode: false
in: path
name: requiredMetricName
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'metrics-requiredMetricName'
tags:
- Actuator
/a1-policy/v2/configuration:
get:
operationId: getConfiguration
responses:
"200":
content:
application/json:
schema:
type: object
description: Configuration
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: File is not found or readable
summary: Returns the contents of the application configuration file
tags:
- Management of configuration
put:
operationId: putConfiguration
requestBody:
content:
application/json:
schema:
type: object
required: true
responses:
"200":
content:
'*/*':
schema:
$ref: '#/components/schemas/void'
description: Configuration updated
"400":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Invalid configuration provided
"500":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Something went wrong when replacing the configuration. Try
again.
summary: Replace the current configuration file with the given configuration
tags:
- Management of configuration
/actuator:
get:
operationId: links
responses:
"200":
content:
'*/*':
schema:
additionalProperties:
additionalProperties:
$ref: '#/components/schemas/Link'
type: object
type: object
description: OK
summary: Actuator root web endpoint
tags:
- Actuator
/actuator/loggers/{name}:
get:
operationId: loggers-name_2
parameters:
- explode: false
in: path
name: name
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'loggers-name'
tags:
- Actuator
post:
operationId: loggers-name
parameters:
- explode: false
in: path
name: name
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'loggers-name'
tags:
- Actuator
/a1-policy/v2/services/{service_id}/keepalive:
put:
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:
- explode: false
in: path
name: service_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
type: object
description: "Service supervision timer refreshed, OK"
"404":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: "The service is not found, needs re-registration"
summary: Heartbeat indicates that the service is running
tags:
- Service Registry and Supervision
/actuator/metrics:
get:
operationId: metrics
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'metrics'
tags:
- Actuator
/a1-policy/v2/rics:
get:
description: The call returns all Near-RT RICs that supports a given policy
type identity
operationId: getRics
parameters:
- description: "The identity of a policy type. If given, all Near-RT RICs supporting\
\ the policy type are returned"
explode: true
in: query
name: policytype_id
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ric_info_list_v2'
description: OK
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Policy type is not found
summary: Query Near-RT RIC information
tags:
- NearRT-RIC Repository
/a1-policy/v2/services:
get:
description: Either information about a registered service with given identity
or all registered services are returned.
operationId: getServices
parameters:
- description: The identity of the service
explode: true
in: query
name: service_id
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/service_list_v2'
description: OK
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Service is not found
summary: Returns service information
tags:
- Service Registry and Supervision
put:
description: "Registering a service is needed to:- Get callbacks about\
\ available NearRT RICs.
- Activate supervision of the service. If a\
\ service is inactive, its policies will automatically be deleted.
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":
content:
'*/*':
schema:
type: object
description: Service updated
"201":
content:
'*/*':
schema:
type: object
description: Service created
"400":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: The ServiceRegistrationInfo is not accepted
summary: Register a service
tags:
- Service Registry and Supervision
/actuator/info:
get:
operationId: info
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'info'
tags:
- Actuator
/status:
get:
operationId: getStatusV1
responses:
"200":
content:
'*/*':
schema:
type: string
description: Service is living
summary: Returns status and statistics of this service
tags:
- Health Check
/a1-policy/v2/policy-types/{policytype_id}:
get:
operationId: getPolicyType
parameters:
- explode: false
in: path
name: policytype_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
$ref: '#/components/schemas/policytype_v2'
description: Policy type
"404":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Policy type is not found
summary: Returns a policy type definition
tags:
- A1 Policy Management
/actuator/logfile:
get:
operationId: logfile
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'logfile'
tags:
- Actuator
/actuator/health:
get:
operationId: health
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'health'
tags:
- Actuator
/a1-policy/v2/policies:
get:
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:
- description: Select policies of a given policy type identity.
explode: true
in: query
name: policytype_id
required: false
schema:
type: string
style: form
- description: Select policies of a given Near-RT RIC identity.
explode: true
in: query
name: ric_id
required: false
schema:
type: string
style: form
- description: Select policies owned by a given service.
explode: true
in: query
name: service_id
required: false
schema:
type: string
style: form
- description: Select policies of types with the given type name (type identity
has the format )
explode: true
in: query
name: type_name
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/policy_id_list_v2'
description: Policy identities
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC or type not found
summary: Query policy identities
tags:
- A1 Policy Management
put:
operationId: putPolicy
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/policy_info_v2'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/void'
description: Policy updated
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/void'
description: Policy created
"423":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC is not operational
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Near-RT RIC or policy type is not found
summary: Create or update a policy
tags:
- A1 Policy Management
/r-app/near-rt-ric-status:
post:
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":
content:
application/json:
schema:
$ref: '#/components/schemas/void'
description: OK
summary: Callback for Near-RT RIC status
tags:
- Callbacks
/a1-policy/v2/services/{service_id}:
delete:
operationId: deleteService
parameters:
- explode: false
in: path
name: service_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
'*/*':
schema:
$ref: '#/components/schemas/void'
description: Not used
"204":
content:
'*/*':
schema:
type: object
description: Service unregistered
"404":
content:
'*/*':
schema:
$ref: '#/components/schemas/error_information'
description: Service not found
summary: Unregister a service
tags:
- Service Registry and Supervision
/actuator/heapdump:
get:
operationId: heapdump
responses:
"200":
content:
'*/*':
schema:
type: object
description: OK
summary: Actuator web endpoint 'heapdump'
tags:
- Actuator
/a1-policy/v2/policies/{policy_id}/status:
get:
operationId: getPolicyStatus
parameters:
- explode: false
in: path
name: policy_id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/policy_status_info_v2'
description: Policy status
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/error_information'
description: Policy is not found
summary: Returns a policy status
tags:
- A1 Policy Management
components:
schemas:
error_information:
description: Problem as defined in https://tools.ietf.org/html/rfc7807
properties:
detail:
description: ' A human-readable explanation specific to this occurrence
of the problem.'
example: Policy type not found
type: string
status:
description: 'The HTTP status code generated by the origin server for this
occurrence of the problem. '
example: 404
format: int32
type: integer
type: object
void:
description: Void/empty
type: object
status_info_v2:
example:
status: status
properties:
status:
description: status text
type: string
type: object
ric_info_v2:
description: Information for a Near-RT RIC
example:
ric_id: ric_id
managed_element_ids:
- managed_element_ids
- managed_element_ids
state: UNAVAILABLE
policytype_ids:
- policytype_ids
- policytype_ids
properties:
ric_id:
description: identity of the Near-RT RIC
type: string
managed_element_ids:
description: O1 identities for managed entities
items:
description: O1 identities for managed entities
type: string
type: array
state:
description: Represents the states for a Near-RT RIC
enum:
- UNAVAILABLE
- AVAILABLE
- SYNCHRONIZING
- CONSISTENCY_CHECK
type: string
policytype_ids:
description: supported policy types
items:
description: supported policy types
type: string
type: array
type: object
service_registration_info_v2:
description: Information for one service
properties:
callback_url:
description: callback for notifying of Near-RT RIC state changes
type: string
service_id:
description: identity of the service
type: string
keep_alive_interval_seconds:
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
type: integer
required:
- service_id
type: object
policy_info_list_v2:
description: List of policy information
example:
policies:
- ric_id: ric_id
policy_id: policy_id
transient: false
service_id: service_id
policy_data: "{}"
status_notification_uri: status_notification_uri
policytype_id: policytype_id
- ric_id: ric_id
policy_id: policy_id
transient: false
service_id: service_id
policy_data: "{}"
status_notification_uri: status_notification_uri
policytype_id: policytype_id
properties:
policies:
description: List of policy information
items:
$ref: '#/components/schemas/policy_info_v2'
type: array
type: object
policy_status_info_v2:
description: Status for one A1-P Policy
example:
last_modified: last_modified
status: "{}"
properties:
last_modified:
description: "timestamp, last modification time"
type: string
status:
description: the Policy status
type: object
type: object
service_status_v2:
description: List of service information
example:
callback_url: callback_url
service_id: service_id
keep_alive_interval_seconds: 0
time_since_last_activity_seconds: 6
properties:
callback_url:
description: callback for notifying of RIC synchronization
type: string
service_id:
description: identity of the service
type: string
keep_alive_interval_seconds:
description: policy keep alive timeout
format: int64
type: integer
time_since_last_activity_seconds:
description: time since last invocation by the service
format: int64
type: integer
type: object
ric_info_list_v2:
description: List of Near-RT RIC information
example:
rics:
- ric_id: ric_id
managed_element_ids:
- managed_element_ids
- managed_element_ids
state: UNAVAILABLE
policytype_ids:
- policytype_ids
- policytype_ids
- ric_id: ric_id
managed_element_ids:
- managed_element_ids
- managed_element_ids
state: UNAVAILABLE
policytype_ids:
- policytype_ids
- policytype_ids
properties:
rics:
description: List of Near-RT RIC information
items:
$ref: '#/components/schemas/ric_info_v2'
type: array
type: object
policytype_v2:
description: Policy type
example:
policy_schema: "{}"
properties:
policy_schema:
description: Policy type json schema. The schema is a json object following
http://json-schema.org/draft-07/schema
type: object
type: object
policytype_id_list_v2:
description: Information about policy types
example:
policytype_ids:
- policytype_ids
- policytype_ids
properties:
policytype_ids:
description: Policy type identities
items:
description: Policy type identities
type: string
type: array
type: object
policy_info_v2:
description: Information for one A1-P Policy
example:
ric_id: ric_id
policy_id: policy_id
transient: false
service_id: service_id
policy_data: "{}"
status_notification_uri: status_notification_uri
policytype_id: policytype_id
properties:
ric_id:
description: identity of the target Near-RT RIC
type: string
policy_id:
description: identity of the policy
type: string
transient:
default: false
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
type: boolean
service_id:
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.
type: string
policy_data:
description: the configuration of the policy
type: object
status_notification_uri:
description: Callback URI for policy status updates
type: string
policytype_id:
description: identity of the policy type
type: string
required:
- policy_data
- policy_id
- policytype_id
- ric_id
type: object
policy_id_list_v2:
description: A list of policy identities
example:
policy_ids:
- policy_ids
- policy_ids
properties:
policy_ids:
description: Policy identities
items:
description: Policy identities
type: string
type: array
type: object
service_list_v2:
description: List of service information
example:
service_list:
- callback_url: callback_url
service_id: service_id
keep_alive_interval_seconds: 0
time_since_last_activity_seconds: 6
- callback_url: callback_url
service_id: service_id
keep_alive_interval_seconds: 0
time_since_last_activity_seconds: 6
properties:
service_list:
description: List of service information
items:
$ref: '#/components/schemas/service_status_v2'
type: array
type: object
service_callback_info_v2:
description: Information transferred as in Service callbacks (callback_url)
properties:
ric_id:
description: identity of a Near-RT RIC
type: string
event_type:
description: "values:\nAVAILABLE: the Near-RT RIC has become available\
\ for A1 Policy management"
enum:
- AVAILABLE
type: string
required:
- event_type
- ric_id
type: object
Link:
properties:
templated:
type: boolean
href:
type: string
type: object