blob: 875e2734ccbdd7b5fa46f8db53b9ea93a8811f2b [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 policices. <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 unavailble, 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 registerred 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 registerring services that uses PMS.
Each A1 policy is owned by a service. PMS can supervise each registerred 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: Management of configuration
- 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/
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'
/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/threaddump:
get:
tags:
- Actuator
summary: Actuator web endpoint 'threaddump'
operationId: threaddump_4
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 Mananged Element identity can
be specified.<br>The intention with Mananged 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/loggers:
get:
tags:
- Actuator
summary: Actuator web endpoint 'loggers'
operationId: loggers_2
responses:
200:
description: OK
content:
'*/*':
schema:
type: object
/actuator/health/**:
get:
tags:
- Actuator
summary: Actuator web endpoint 'health-path'
operationId: health-path_2
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_2
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_1
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_4
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_3
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 registerred service must call this in regular intervals to indicate
that it is in operation. Absence of this call will lead to that the service
will be deregisterred and all its policies are removed.
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_2
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_2
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_2
responses:
200:
description: OK
content:
'*/*':
schema:
type: object
/actuator/health:
get:
tags:
- Actuator
summary: Actuator web endpoint 'health'
operationId: health_2
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 registerred 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'
/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'
/actuator/heapdump:
get:
tags:
- Actuator
summary: Actuator web endpoint 'heapdump'
operationId: heapdump_2
responses:
200:
description: OK
content:
'*/*':
schema:
type: object
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 a heartbeat supervision
of the service, which in regular intevals must invoke a 'keepalive' REST
call. When a service does not invoke this call within the given time,
it is considered unavailble. An unavailable service will be automatically
deregistered and its policies will be deleted. Value 0 means no timeout
supervision.
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 scema. 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