1 # ============LICENSE_START=======================================================
2 # Copyright (C) 2020-2023 Nordix Foundation
3 # Copyright (C) 2023-2024 OpenInfra Foundation Europe. All rights reserved.
4 # Modifications Copyright (C) 2021 Pantheon.tech
5 # Modifications Copyright (C) 2021 Bell Canada
6 # ================================================================================
7 # Licensed under the Apache License, Version 2.0 (the "License");
8 # you may not use this file except in compliance with the License.
9 # You may obtain a copy of the License at
11 # http://www.apache.org/licenses/LICENSE-2.0
13 # Unless required by applicable law or agreed to in writing, software
14 # distributed under the License is distributed on an "AS IS" BASIS,
15 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 # See the License for the specific language governing permissions and
17 # limitations under the License.
19 # SPDX-License-Identifier: Apache-2.0
20 # ============LICENSE_END=========================================================
24 x-api-id: a31c510b-20e6-4a08-af16-368c44d7fba8
25 x-audience: external-public
26 description: "<h2>General</h2><p>The O-RAN Non-RT RIC Policy Management Service\
27 \ provides a REST API for managemecnt of A1 policies. <br/>The main tasks of the\
28 \ service are:</p><ul><li>A1 Policy creation, modification and deletion.</li><li>Monitoring\
29 \ and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs</li><li>Maintaining\
30 \ a view of supported Near-RT RIC policy types</li><li>Supervision of using services\
31 \ (R-APPs). When a service is unavailable, its policies are removed.</li></ul><h2>APIs\
32 \ provided or defined by the service</h2><h3>A1 Policy Management</h3><p>This\
33 \ is an API for management of A1 Policies.</p><ul><li>A1 Policy retrieval, creation,\
34 \ modification and deletion.</li><li>Retrieval of supported A1 Policy types for\
35 \ a Near-RT RIC</li><li>Retrieval of status for existing A1 policies</li></ul><h3>Management\
36 \ of configuration</h3><p>API for updating and retrieval of the component configuration.\
37 \ Note that there other ways to maintain the configuration.</p><h3>Service callbacks</h3><p>These\
38 \ are endpoints that are invoked by this service. The callbacks are registered\
39 \ in this service at service registration.</p><h3>NearRT-RIC Repository</h3><p>This\
40 \ is an API that provides support for looking up a NearRT-RIC. Each A1 policy\
41 \ is targeted for one Near-RT RIC.</p><h3>Health Check</h3><p>API used for supervision\
42 \ of the PMS component.</p><h3>Service Registry and Supervision</h3><p>API used\
43 \ for registering services that uses PMS. Each A1 policy is optionally owned by\
44 \ a service. PMS can supervise each registered service by a heart-beat supervision\
45 \ and will automatically remove policies for unavailable services. Note that a\
46 \ service does not need to be registered in order to create A1 Policies. This\
47 \ is a feature that is optional to use.</p><h3>Authorization API</h3><p>API used\
48 \ for access control of A1 Policy access. If configured, an external authorization\
49 \ provider is requested to grant access to the A1 Policy type.</p><h3>Spring Boot\
50 \ Actuator</h3><p>Provides generic functions used to monitor and manage the Spring\
51 \ web application.</p>"
53 name: Copyright (C) 2020-2023 Nordix Foundation. Licensed under the Apache License.
54 url: http://www.apache.org/licenses/LICENSE-2.0
55 title: A1 Policy Management Service
58 url: https://www.onap.org/
59 email: discuss-list@onap.com
63 - name: A1 Policy Management
64 description: "API used to create polices, Policy Instances and get them as individual
65 using an ID or get all policies/Instances."
66 - name: NearRT-RIC Repository
67 description: "API used to get the NearRT-RIC for the managed element."
68 - name: Service Registry and Supervision
69 description: "API used to keep the service Alive with in the timeout period"
71 description: "API used to get the health status and statistics of this service"
72 - name: Service callbacks
73 - name: Authorization API
74 description: "API used for authorization of information A1 policy access (this is
75 provided by an authorization producer such as OPA). <br> Note that this API is called
76 by PMS, it is not provided."
78 description: "API used to create or fetch the application configuration."
80 description: Monitor and interact
82 description: Spring Boot Actuator Web API Documentation
83 url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
85 /a1-policy/v2/policy-instances:
87 description: "Returns a list of A1 policies matching given search criteria.\
88 \ <br>If several query parameters are defined, the policies matching all conditions\
90 operationId: getPolicyInstances
92 - description: Select policies with a given type identity.
100 - description: Select policies for a given Near-RT RIC identity.
108 - description: Select policies owned by a given service.
116 - description: Select policies of a given type name (type identity has the format
131 $ref: '#/components/examples/policy_info_list'
133 $ref: '#/components/schemas/policy_info_list'
134 description: OK - Returns A1 Policies which matches the criteria
139 $ref: '#/components/schemas/error_information'
140 description: "Not Found - Near-RT RIC, policy type or service not found"
141 summary: Query for A1 policy instances
143 - A1 Policy Management
144 /example-authz-check:
146 description: The authorization function decides if access is granted.
147 operationId: performAccessControl
152 $ref: '#/components/schemas/policy_authorization'
159 $ref: '#/components/schemas/authorization_result'
162 $ref: '#/components/responses/Forbidden'
163 summary: Request for access authorization.
166 /actuator/threaddump:
169 operationId: threaddump
173 text/plain;charset=UTF-8:
176 application/vnd.spring-boot.actuator.v3+json:
182 application/vnd.spring-boot.actuator.v2+json:
186 summary: Actuator web endpoint 'threaddump'
189 /a1-policy/v2/status:
191 operationId: getStatus
197 $ref: '#/components/schemas/status_info'
200 $ref: '#/components/examples/status_info'
201 description: OK- Service is living Ok
202 description: Returns status and statistics of this service
212 application/vnd.spring-boot.actuator.v3+json:
218 application/vnd.spring-boot.actuator.v2+json:
222 summary: Actuator web endpoint 'loggers'
228 operationId: health-path
232 application/vnd.spring-boot.actuator.v3+json:
238 application/vnd.spring-boot.actuator.v2+json:
242 summary: Actuator web endpoint 'health-path'
245 /a1-policy/v2/rics/ric:
247 description: Either a Near-RT RIC identity or a Managed Element identity can
248 be specified.<br>The intention with Managed Element identity is the ID used
249 in O1 for accessing the traffical element (such as the ID of CU).
252 - description: "The identity of a Managed Element. If given, the Near-RT RIC\
253 \ managing the ME is returned."
256 name: managed_element_id
261 - description: The identity of a Near-RT RIC to get information for.
274 $ref: '#/components/schemas/ric_info'
277 $ref: '#/components/examples/ric_info'
278 description: OK - Near-RT RIC is found
280 $ref: '#/components/responses/NotFound'
281 description: NotFound - Requested NearRT-RIC Not Found
282 summary: Returns info of Near-RT RIC queried by the ric-id and managed-element-id
284 - NearRT-RIC Repository
288 operationId: shutdown
292 application/vnd.spring-boot.actuator.v3+json:
298 application/vnd.spring-boot.actuator.v2+json:
302 summary: Actuator web endpoint 'shutdown'
305 /a1-policy/v2/policy-types:
307 operationId: getPolicyTypes
309 - description: Select types for the given Near-RT RIC identity.
317 - description: Select types with the given type name (type identity has the
318 format <typename_version>)
326 - description: Select types that are compatible with the given version. This
327 parameter is only applicable in conjunction with type_name. As an example
328 version 1.9.1 is compatible with 1.0.0 but not the other way around. Matching
329 types will be returned sorted in ascending order.
332 name: compatible_with_version
343 $ref: '#/components/examples/policy_type_id_list'
345 $ref: '#/components/schemas/policy_type_id_list'
346 description: OK - Policy Type IDs Found
348 $ref: '#/components/responses/NotFound'
349 description: 'Not Found - Requested Policy Type IDs Not Found'
350 description: Query policy type identities
352 - A1 Policy Management
353 /a1-policy/v2/policies/{policy_id}:
355 description: Deleting the policy using the Policy's Policy ID.
356 operationId: deletePolicy
370 $ref: '#/components/schemas/void'
371 description: OK - Policy deleted
373 $ref: '#/components/responses/Locked'
374 description: 'The requested policy using policy_id is Locked'
375 summary: Delete a policy
377 - A1 Policy Management
379 operationId: getPolicy
393 $ref: '#/components/schemas/policy_info'
396 $ref: '#/components/examples/policy_info'
397 description: OK - Policy found
399 $ref: '#/components/responses/NotFound'
400 description: 'Not Found - Requested Policy using policy_id is not found'
401 description: Returns a policy
403 - A1 Policy Management
404 /actuator/metrics/{requiredMetricName}:
407 operationId: metrics-requiredMetricName
411 name: requiredMetricName
419 application/vnd.spring-boot.actuator.v3+json:
425 application/vnd.spring-boot.actuator.v2+json:
429 summary: Actuator web endpoint 'metrics-requiredMetricName'
432 /a1-policy/v2/configuration:
435 operationId: getConfiguration
442 description: OK - Configuration
444 $ref: '#/components/responses/NotFound'
445 description: Not Found - Configuration is not found or readable
446 description: Returns the contents of the application configuration file
451 operationId: putConfiguration
463 $ref: '#/components/schemas/void'
464 description: OK - Configuration updated
466 $ref: '#/components/responses/BadRequest'
467 description: Replace the current configuration with the given configuration
477 application/vnd.spring-boot.actuator.v3+json:
479 additionalProperties:
480 additionalProperties:
481 $ref: '#/components/schemas/Link'
486 additionalProperties:
487 additionalProperties:
488 $ref: '#/components/schemas/Link'
491 application/vnd.spring-boot.actuator.v2+json:
493 additionalProperties:
494 additionalProperties:
495 $ref: '#/components/schemas/Link'
499 summary: Actuator root web endpoint
502 /actuator/loggers/{name}:
505 operationId: loggers-name
517 application/vnd.spring-boot.actuator.v3+json:
523 application/vnd.spring-boot.actuator.v2+json:
527 summary: Actuator web endpoint 'loggers-name'
532 operationId: loggers-name_2
561 summary: Actuator web endpoint 'loggers-name'
564 /a1-policy/v2/services/{service_id}/keepalive:
566 description: A registered service should invoke this operation regularly to
567 indicate that it is still alive. If a registered service fails to invoke this
568 operation before the end of a timeout period the service will be deregistered
569 and all its A1 policies wil be removed. (This timeout can be set or disabled
570 when each service is initially registered)
571 operationId: keepAliveService
586 description: "OK - Service supervision timer refreshed, OK"
588 $ref: '#/components/responses/NotFound'
589 summary: Heartbeat indicates that the service is running
591 - Service Registry and Supervision
599 application/vnd.spring-boot.actuator.v3+json:
605 application/vnd.spring-boot.actuator.v2+json:
609 summary: Actuator web endpoint 'metrics'
614 description: The call returns all Near-RT RICs that supports a given policy
618 - description: "The identity of a policy type. If given, all Near-RT RICs supporting\
619 \ the policy type are returned"
632 $ref: '#/components/schemas/ric_info_list'
635 $ref: '#/components/examples/ric_info_list'
638 $ref: '#/components/responses/NotFound'
639 summary: Query Near-RT RIC information
641 - NearRT-RIC Repository
642 /a1-policy/v2/services:
644 description: Either information about a registered service with given identity
645 or all registered services are returned.
646 operationId: getServices
648 - description: The identity of the service
661 $ref: '#/components/schemas/service_status_list'
664 $ref: '#/components/examples/service_status_list'
667 $ref: '#/components/responses/NotFound'
668 summary: Returns service information
670 - Service Registry and Supervision
672 description: "Registering a service is needed to:<ul><li>Get callbacks about\
673 \ available NearRT RICs.</li><li>Activate supervision of the service. If a\
674 \ service is inactive, its policies will automatically be deleted.</li></ul>Policies\
675 \ can be created even if the service is not registerred. This is a feature\
676 \ which it is optional to use."
677 operationId: putService
682 $ref: '#/components/schemas/service_registration_info'
690 description: OK - Service updated
696 description: Created - Service created
698 $ref: '#/components/responses/BadRequest'
699 summary: Register a service
701 - Service Registry and Supervision
704 "{$request.body#/callback_url}":
706 description: The URL to this call is registered at Service registration.
707 operationId: serviceCallback
712 $ref: '#/components/schemas/service_callback_info_v2'
719 $ref: '#/components/schemas/void'
722 $ref: '#/components/responses/NotFound'
723 summary: Callback for Near-RT RIC status
733 application/vnd.spring-boot.actuator.v3+json:
739 application/vnd.spring-boot.actuator.v2+json:
743 summary: Actuator web endpoint 'info'
748 operationId: getStatusV1
755 description: OK - Service is living
756 description: Returns status and statistics of this service
759 /a1-policy/v2/policy-types/{policytype_id}:
761 operationId: getPolicyTypeDefinition
775 $ref: '#/components/schemas/policy_type_definition'
777 policy_type_definition:
778 $ref: '#/components/examples/policy_type_definition'
779 description: OK - schema of the given policy type
781 $ref: '#/components/responses/NotFound'
782 description: Returns a policy type definition
784 - A1 Policy Management
792 text/plain;charset=UTF-8:
796 summary: Actuator web endpoint 'logfile'
806 application/vnd.spring-boot.actuator.v3+json:
812 application/vnd.spring-boot.actuator.v2+json:
816 summary: Actuator web endpoint 'health'
819 /a1-policy/v2/policies:
821 description: "Returns a list of A1 policies matching given search criteria.\
822 \ <br>If several query parameters are defined, the policies matching all conditions\
824 operationId: getPolicyIds
826 - description: Select policies of a given policy type identity.
834 - description: Select policies of a given Near-RT RIC identity.
842 - description: Select policies owned by a given service.
850 - description: Select policies of types with the given type name (type identity
851 has the format <typename_version>)
865 $ref: '#/components/examples/policy_id_list'
867 $ref: '#/components/schemas/policy_id_list'
868 description: OK - Policy identities
870 $ref: '#/components/responses/NotFound'
871 summary: Query policy identities
873 - A1 Policy Management
875 operationId: putPolicy
880 $ref: '#/components/schemas/policy_info'
887 $ref: '#/components/schemas/void'
888 description: OK - Policy updated
893 $ref: '#/components/schemas/void'
894 description: Created - Policy created
896 $ref: '#/components/responses/Locked'
897 description: Create or update a policy
899 - A1 Policy Management
900 /a1-policy/v2/services/{service_id}:
902 operationId: deleteService
917 description: No Content - Service unregistered
919 $ref: '#/components/responses/NotFound'
920 description: Unregister a service
922 - Service Registry and Supervision
926 operationId: heapdump
930 application/octet-stream:
934 summary: Actuator web endpoint 'heapdump'
937 /a1-policy/v2/policies/{policy_id}/status:
939 operationId: getPolicyStatus
953 $ref: '#/components/schemas/policy_status_info'
956 $ref: '#/components/examples/policy_status_info'
957 description: OK - Policy status
959 $ref: '#/components/responses/NotFound'
960 description: Returns a policy status
962 - A1 Policy Management
966 description: "Locked - HTTP Status code which can be used when the state is Locked"
968 application/problem+json:
970 $ref: '#/components/schemas/error_information'
974 detail: Requested resource is in a locked state.
976 description: Bad Request
978 application/problem+json:
980 $ref: '#/components/schemas/error_information'
984 detail: The provided request is not valid.
986 description: Forbidden
988 application/problem+json:
990 $ref: '#/components/schemas/error_information'
994 detail: Your role does not allow to perform this action. Contact System Administrator to change your access rights.
996 description: Not Found
998 application/problem+json:
1004 description: List of service information
1006 callback_url: callback_url
1007 service_id: service_id
1008 keep_alive_interval_seconds: 0
1009 time_since_last_activity_seconds: 6
1011 service_status_list:
1012 description: List of service information
1015 - callback_url: callback_url
1016 service_id: service_id
1017 keep_alive_interval_seconds: 0
1018 time_since_last_activity_seconds: 6
1019 - callback_url: callback_url
1020 service_id: service_id
1021 keep_alive_interval_seconds: 0
1022 time_since_last_activity_seconds: 6
1023 policy_type_definition:
1024 description: Schema of the given Policy type
1027 policy_type_id_list:
1028 description: Array of policy type id's
1030 policy_type_id_list:
1034 description: Policy information of one A1-P policy
1037 policy_id: policy_id
1039 service_id: service_id
1041 status_notification_uri: status_notification_uri
1042 policytype_id: policytype_id
1044 description: List of policy information
1048 policy_id: policy_id
1050 service_id: service_id
1052 status_notification_uri: status_notification_uri
1053 policytype_id: policytype_id
1055 policy_id: policy_id
1057 service_id: service_id
1059 status_notification_uri: status_notification_uri
1060 policytype_id: policytype_id
1062 description: A list of policy identities
1068 description: Status for one A1-P Policy
1070 last_modified: last_modified
1080 managed_element_ids:
1081 - some_managed_element_id
1082 - some_managed_element_id
1085 - some_policytype_id
1086 - some_policytype_id
1091 managed_element_ids:
1092 - some_managed_element_id
1093 - some_managed_element_id
1099 managed_element_ids:
1100 - managed_element_ids
1101 - managed_element_ids
1108 policy_type_definition:
1109 description: Contains policy type schema definition
1113 description: Policy type json schema. The schema is a json object following
1114 http://json-schema.org/draft-07/schema
1117 description: Problem as defined in https://tools.ietf.org/html/rfc7807
1120 description: ' A human-readable explanation specific to this occurrence
1122 example: Policy type not found
1125 description: 'A specific error name'
1129 description: 'The HTTP status code generated by the origin server for this
1130 occurrence of the problem. '
1136 description: Void/empty
1141 description: status text
1144 authorization_result:
1145 description: Result of authorization
1150 description: "If true, the access is granted"
1156 description: Information for a Near-RT RIC
1159 description: identity of the Near-RT RIC
1161 managed_element_ids:
1162 description: O1 identities for managed entities
1164 description: O1 identities for managed entities
1168 description: Represents the states for a Near-RT RIC
1176 description: supported policy types
1178 description: supported policy types
1182 service_registration_info:
1183 description: Information for one service
1186 description: callback for notifying of Near-RT RIC state changes
1189 description: identity of the service
1191 keep_alive_interval_seconds:
1192 description: "keep alive interval for the service. This is used to enable\
1193 \ optional heartbeat supervision of the service. If set (> 0) the registered\
1194 \ service should regularly invoke a 'keepalive' REST call. When a service\
1195 \ fails to invoke this 'keepalive' call within the configured time, the\
1196 \ service is considered unavailable. An unavailable service will be automatically\
1197 \ deregistered and its policies will be deleted. Value 0 means timeout\
1198 \ supervision is disabled."
1205 description: List of policy information
1208 description: List of policy information
1210 $ref: '#/components/schemas/policy_info'
1214 description: Status for one A1-P Policy
1217 description: "timestamp, last modification time"
1220 description: the Policy status
1226 description: callback for notifying of RIC synchronization
1229 description: identity of the service
1231 keep_alive_interval_seconds:
1232 description: policy keep alive timeout
1235 time_since_last_activity_seconds:
1236 description: time since last invocation by the service
1241 description: List of Near-RT RIC information
1244 description: List of Near-RT RIC information
1246 $ref: '#/components/schemas/ric_info'
1253 description: Access type
1260 description: Authorization token
1263 description: Policy type identifier
1270 policy_authorization:
1271 description: Authorization request for A1 policy requests
1274 $ref: '#/components/schemas/input'
1278 policy_type_id_list:
1279 description: Information about policy types
1282 description: Policy type identities
1284 description: Policy type identities
1289 description: Information for one A1-P Policy
1292 description: identity of the target Near-RT RIC
1295 description: identity of the policy
1299 description: "if true, the policy is deleted at RIC restart. If false, its\
1300 \ value is maintained by this service until explicitly deleted. Default\
1306 description: the identity of the service owning the policy. This can be
1307 used to group the policies (it is possible to get all policies associated
1308 to a service). Note that the service does not need to be registered.
1311 description: the configuration of the policy
1313 status_notification_uri:
1314 description: Callback URI for policy status updates
1317 description: identity of the policy type
1327 description: A list of policy identities
1334 description: Policy identities
1336 description: Policy identities
1340 service_status_list:
1343 description: List of service information
1345 $ref: '#/components/schemas/service_status'
1348 service_callback_info_v2:
1349 description: Information transferred as in Service callbacks (callback_url)
1352 description: identity of a Near-RT RIC
1355 description: "values:\nAVAILABLE: the Near-RT RIC has become available\
1356 \ for A1 Policy management"