blob: 1f84399ed7c35307a066fd81d54f2941a6d9f5de [file] [log] [blame]
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 owned by a service. PMS can supervise each registered service
and will automatically remove policies for unavailable services.</p>
license:
name: Copyright (C) 2020-2022 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'
/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.</li><li>Activate
supervision of the service. If a service is inactive, its policies will be
deleted.</li></ul>
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
- service_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.
service_id:
type: string
description: the identity of the service owning the policy
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