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:

APIs\ \ provided or defined 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.

Service 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.

Authorization API

API used\ \ for access control of A1 Policy access. If configured, an external authorization\ \ provider is requested to grant access to the A1 Policy type.

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.2.0 servers: - url: / tags: - description: "API used for authorization of information A1 policy access (this is\ \ provided by an authorization producer such as OPA).\nNote that this API is called\ \ by PMS, it is not provided.\n" name: Authorization API - 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 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 /example-authz-check: post: description: The authorization function decides if access is granted. operationId: performAccessControl requestBody: content: application/json: schema: $ref: '#/components/schemas/policy_authorization' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/authorization_result' description: OK summary: Request for access authorization. tags: - Authorization API /actuator/threaddump: get: operationId: threaddump responses: "200": content: text/plain;charset=UTF-8: schema: type: object application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: schema: type: object description: OK summary: Actuator web endpoint 'loggers' tags: - Actuator /actuator/health/**: get: operationId: health-path responses: "200": content: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: application/vnd.spring-boot.actuator.v3+json: schema: additionalProperties: additionalProperties: $ref: '#/components/schemas/Link' type: object type: object application/json: schema: additionalProperties: additionalProperties: $ref: '#/components/schemas/Link' type: object type: object application/vnd.spring-boot.actuator.v2+json: 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 parameters: - explode: false in: path name: name required: true schema: type: string style: simple responses: "200": content: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: schema: type: object description: OK summary: Actuator web endpoint 'loggers-name' tags: - Actuator post: operationId: loggers-name_2 parameters: - explode: false in: path name: name required: true schema: type: string style: simple requestBody: content: application/json: schema: enum: - TRACE - DEBUG - INFO - WARN - ERROR - FATAL - "OFF" type: string 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: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: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: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: text/plain;charset=UTF-8: schema: type: object description: OK summary: Actuator web endpoint 'logfile' tags: - Actuator /actuator/health: get: operationId: health responses: "200": content: application/vnd.spring-boot.actuator.v3+json: schema: type: object application/json: schema: type: object application/vnd.spring-boot.actuator.v2+json: 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: - Service 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: application/octet-stream: 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 authorization_result: description: Result of authorization example: result: true properties: result: description: "If true, the access is granted" type: boolean required: - result 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 input: description: input properties: access_type: description: Access type enum: - READ - WRITE - DELETE type: string auth_token: description: Authorization token type: string policy_type_id: description: Policy type identifier type: string required: - access_type - auth_token - policy_type_id type: object policy_authorization: description: Authorization request for A1 policy requests properties: input: $ref: '#/components/schemas/input' required: - input 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 registered. 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