1 # ============LICENSE_START=======================================================
2 # Copyright (C) 2024 OpenInfra Foundation Europe. All rights reserved.
3 # ================================================================================
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at
8 # http://www.apache.org/licenses/LICENSE-2.0
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
16 # SPDX-License-Identifier: Apache-2.0
17 # ============LICENSE_END=========================================================
21 title: 'A1 policy management API'
23 x-api-id: a31c510b-20e6-4a08-af16-368c44d7fba8
24 x-audience: external-public
25 description: "<h2>General</h2><p>The O-RAN Non-RT RIC Policy Management Service\
26 \ provides a REST API for managemecnt of A1 policies. <br/>The main tasks of the\
27 \ service are:</p><ul><li>A1 Policy creation, modification and deletion.</li><li>Monitoring\
28 \ and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs</li><li>Maintaining\
29 \ a view of supported Near-RT RIC policy types</li><li>Supervision of using services\
30 \ (R-APPs). When a service is unavailable, its policies are removed.</li></ul><h2>APIs\
31 \ provided or defined by the service</h2><h3>A1 Policy Management</h3><p>This\
32 \ is an API for management of A1 Policies.</p><ul><li>A1 Policy retrieval, creation,\
33 \ modification and deletion.</li><li>Retrieval of supported A1 Policy types for\
34 \ a Near-RT RIC</li><li>Retrieval of status for existing A1 policies</li></ul><h3>Management\
35 \ of configuration</h3><p>API for updating and retrieval of the component configuration.\
36 \ Note that there other ways to maintain the configuration.</p><h3>Service callbacks</h3><p>These\
37 \ are endpoints that are invoked by this service. The callbacks are registered\
38 \ in this service at service registration.</p><h3>NearRT-RIC Repository</h3><p>This\
39 \ is an API that provides support for looking up a NearRT-RIC. Each A1 policy\
40 \ is targeted for one Near-RT RIC.</p><h3>Health Check</h3><p>API used for supervision\
41 \ of the PMS component.</p><h3>Service Registry and Supervision</h3><p>API used\
42 \ for registering services that uses PMS. Each A1 policy is optionally owned by\
43 \ a service. PMS can supervise each registered service by a heart-beat supervision\
44 \ and will automatically remove policies for unavailable services. Note that a\
45 \ service does not need to be registered in order to create A1 Policies. This\
46 \ is a feature that is optional to use.</p><h3>Authorization API</h3><p>API used\
47 \ for access control of A1 Policy access. If configured, an external authorization\
48 \ provider is requested to grant access to the A1 Policy type.</p>"
50 name: Copyright (C) 2024 OpenInfra Foundation Europe. Licensed under the Apache License.
51 url: http://www.apache.org/licenses/LICENSE-2.0
53 url: https://www.onap.org/
54 email: discuss-list@onap.com
56 - url: '{apiRoot}/a1policymanagement/v1'
59 description: 'apiRoot is the Host:port/Domain name of the service where the A1Pms running'
60 default: 'https://a1-pms.com'
62 - name: A1 Policy Management
63 description: "API used to create polices, Policy Instances and get \ them as individual using an ID or get all policies/Instances."
64 - name: NearRT-RIC Repository
65 description: "API used to get the NearRT-RIC for the managed element."
66 - name: Service Registry and Supervision
67 description: "API used to keep the service Alive with in the timeout period"
69 description: "API used to get the health status and statistics of this service"
70 - name: Service callbacks
72 description: "API used to create or fetch the application configuration."
76 operationId: getStatus
82 $ref: '#/components/schemas/StatusInfo'
85 $ref: '#/components/examples/StatusInfo'
86 description: OK- Service is living Ok
87 description: Returns status and statistics of this service
92 description: Either a Near-RT RIC identity or a Managed Element identity can
93 be specified.<br>The intention with Managed Element identity is the ID used
94 in O1 for accessing the traffical element (such as the ID of CU).
97 - description: "The identity of a Managed Element. If given, the Near-RT RIC managing the ME is returned."
100 name: managedElementId
105 - description: The identity of a Near-RT RIC to get information for.
113 - description: Specifies the content type that the client expects to receive in response to the request.
114 Only application/json is allowed.
119 example: application/json
125 $ref: '#/components/schemas/RicInfo'
128 $ref: '#/components/examples/RicInfo'
129 description: OK - Near-RT RIC is found OK
131 $ref: '#/components/responses/404'
132 summary: Returns info for one Near-RT RIC
134 - NearRT-RIC Repository
137 description: The call returns all Near-RT RICs that supports a given policy
141 - description: "The identity of a policy type. If given, all Near-RT RICs supporting the policy type are returned"
149 - description: Specifies the content type that the client expects to receive in response to the request.
150 Only application/json is allowed.
155 example: application/json
161 $ref: '#/components/schemas/RicInfoList'
164 $ref: '#/components/examples/RicInfoList'
167 $ref: '#/components/responses/404'
168 summary: Query Near-RT RIC information
170 - NearRT-RIC Repository
173 operationId: getPolicyTypes
175 - description: Select types for the given Near-RT RIC identity.
183 - description: Select types with the given type name (type identity has the
184 format <typename_version>)
192 - description: Select types that are compatible with the given version. This
193 parameter is only applicable in conjunction with type_name. As an example
194 version 1.9.1 is compatible with 1.0.0 but not the other way around. Matching
195 types will be returned sorted in ascending order.
198 name: compatibleWithVersion
203 - description: Specifies the content type that the client expects to receive in response to the request.
204 Only application/json is allowed.
209 example: application/json
216 $ref: '#/components/schemas/PolicyTypeInformation'
219 description: OK - Policy Type IDs found Ok
221 $ref: '#/components/responses/400'
223 $ref: '#/components/responses/401'
225 $ref: '#/components/responses/403'
227 $ref: '#/components/responses/404'
229 $ref: '#/components/responses/406'
231 $ref: '#/components/responses/429'
233 $ref: '#/components/responses/500'
235 $ref: '#/components/responses/502'
237 $ref: '#/components/responses/503'
238 description: Query policy type identities
240 - A1 Policy Management
241 /policytypes/{policyTypeId}:
243 operationId: getPolicyTypeDefinition
252 - description: Specifies the content type that the client expects to receive in response to the request.
253 Only application/json is allowed.
258 example: application/json
264 $ref: '#/components/schemas/PolicyObject'
267 $ref: '#/components/examples/PolicyObject'
268 description: OK - schema of the given policy type
270 $ref: '#/components/responses/400'
272 $ref: '#/components/responses/401'
274 $ref: '#/components/responses/403'
276 $ref: '#/components/responses/404'
278 $ref: '#/components/responses/406'
280 $ref: '#/components/responses/429'
282 $ref: '#/components/responses/500'
284 $ref: '#/components/responses/502'
286 $ref: '#/components/responses/503'
287 description: Returns a policy type definition
289 - A1 Policy Management
290 /policies/{policyId}:
292 operationId: putPolicy
304 $ref: '#/components/schemas/PolicyObject'
307 $ref: '#/components/examples/PolicyObject'
313 $ref: '#/components/schemas/PolicyObject'
314 description: OK - Policy updated
316 $ref: '#/components/responses/400'
318 $ref: '#/components/responses/401'
320 $ref: '#/components/responses/403'
322 $ref: '#/components/responses/404'
324 $ref: '#/components/responses/406'
326 $ref: '#/components/responses/411'
328 $ref: '#/components/responses/413'
330 $ref: '#/components/responses/415'
332 $ref: '#/components/responses/Locked'
334 $ref: '#/components/responses/429'
336 $ref: '#/components/responses/500'
338 $ref: '#/components/responses/502'
340 $ref: '#/components/responses/503'
341 description: update a policy
343 - A1 Policy Management
345 description: Deleting the policy using policyId.
346 operationId: deletePolicy
355 - description: Specifies the content type that the client expects to receive in response to the request.
356 Only application/json is allowed.
361 example: application/json
364 description: 'The created A1 policy was deleted'
366 $ref: '#/components/responses/400'
368 $ref: '#/components/responses/401'
370 $ref: '#/components/responses/403'
372 $ref: '#/components/responses/404'
374 $ref: '#/components/responses/Locked'
376 $ref: '#/components/responses/429'
378 $ref: '#/components/responses/500'
380 $ref: '#/components/responses/502'
382 $ref: '#/components/responses/503'
383 summary: Delete a policy
385 - A1 Policy Management
387 operationId: getPolicy
396 - description: Specifies the content type that the client expects to receive in response to the request.
397 Only application/json is allowed.
402 example: application/json
408 $ref: '#/components/schemas/PolicyObject'
411 $ref: '#/components/examples/PolicyObject'
412 description: OK - Policy found
414 $ref: '#/components/responses/400'
416 $ref: '#/components/responses/401'
418 $ref: '#/components/responses/403'
420 $ref: '#/components/responses/404'
422 $ref: '#/components/responses/406'
424 $ref: '#/components/responses/429'
426 $ref: '#/components/responses/500'
428 $ref: '#/components/responses/502'
430 $ref: '#/components/responses/503'
431 description: Returns a policy
433 - A1 Policy Management
436 description: "Returns a list of A1 policies matching given search criteria.\
437 \ <br>If several query parameters are defined, the policies matching all conditions\
439 operationId: getPolicyIds
441 - description: Select policies of a given policy type identity.
449 - description: Select policies of a given Near-RT RIC identity.
457 - description: Select policies owned by a given service.
465 - description: Select policies of types with the given type name (type identity
466 has the format <typename_version>)
474 - description: Specifies the content type that the client expects to receive in response to the request.
475 Only application/json is allowed.
480 example: application/json
487 $ref: '#/components/schemas/PolicyInformation'
489 description: OK - Policy identities
491 $ref: '#/components/responses/400'
493 $ref: '#/components/responses/401'
495 $ref: '#/components/responses/403'
497 $ref: '#/components/responses/404'
499 $ref: '#/components/responses/406'
501 $ref: '#/components/responses/429'
503 $ref: '#/components/responses/500'
505 $ref: '#/components/responses/502'
507 $ref: '#/components/responses/503'
508 summary: Query policy identities
510 - A1 Policy Management
512 operationId: createPolicy
518 $ref: '#/components/schemas/PolicyObjectInformation'
521 description: 'Success case 201 created'
525 $ref: '#/components/schemas/PolicyObjectInformation'
528 description: 'Contains the URI of the newly created resource'
533 $ref: '#/components/responses/400'
535 $ref: '#/components/responses/401'
537 $ref: '#/components/responses/403'
539 $ref: '#/components/responses/404'
541 $ref: '#/components/responses/406'
543 $ref: '#/components/responses/Locked'
545 $ref: '#/components/responses/429'
547 $ref: '#/components/responses/500'
549 $ref: '#/components/responses/502'
551 $ref: '#/components/responses/503'
552 description: 'To create A1 policies'
554 - A1 Policy Management
557 operationId: getConfiguration
564 description: OK - Application configuration received
566 $ref: '#/components/responses/404'
568 description: Returns the contents of the application configuration
572 operationId: putConfiguration
584 $ref: '#/components/schemas/void'
585 description: OK - Configuration updated
587 $ref: '#/components/responses/400'
588 description: Replace the current configuration file with the given configuration
591 /services/{serviceId}/keepalive:
593 description: A registered service should invoke this operation regularly to
594 indicate that it is still alive. If a registered service fails to invoke this
595 operation before the end of a timeout period the service will be deregistered
596 and all its A1 policies wil be removed. (This timeout can be set or disabled
597 when each service is initially registered)
598 operationId: keepAliveService
607 - description: Specifies the content type that the client expects to receive in response to the request.
608 Only application/json is allowed.
613 example: application/json
626 description: "OK - Service supervision timer refreshed, OK"
628 $ref: '#/components/responses/404'
629 summary: Heartbeat indicates that the service is running
631 - Service Registry and Supervision
634 description: Either information about a registered service with given identity
635 or all registered services are returned.
636 operationId: getServices
638 - description: The identity of the service
646 - description: Specifies the content type that the client expects to receive in response to the request.
647 Only application/json is allowed.
652 example: application/json
658 $ref: '#/components/schemas/ServiceStatusList'
661 $ref: '#/components/examples/ServiceStatusList'
664 $ref: '#/components/responses/404'
665 summary: Returns service information
667 - Service Registry and Supervision
669 description: "Registering a service is needed to:<ul><li>Get callbacks about\
670 \ available NearRT RICs.</li><li>Activate supervision of the service. If a\
671 \ service is inactive, its policies will automatically be deleted.</li></ul>Policies\
672 \ can be created even if the service is not registerred. This is a feature\
673 \ which it is optional to use."
674 operationId: putService
679 $ref: '#/components/schemas/ServiceRegistrationInfo'
687 description: OK - Service updated
693 description: Created - Service created
695 $ref: '#/components/responses/400'
696 summary: Register a service
698 - Service Registry and Supervision
701 "{$request.body#/callback_url}":
703 description: The URL to this call is registered at Service registration.
704 operationId: serviceCallback
709 $ref: '#/components/schemas/ServiceCallbackInfo'
716 $ref: '#/components/schemas/void'
719 $ref: '#/components/responses/404'
720 summary: Callback for Near-RT RIC status
723 /services/{serviceId}:
725 operationId: deleteService
734 - description: Specifies the content type that the client expects to receive in response to the request.
735 Only application/json is allowed.
740 example: application/json
747 description: No Content - Service unregistered
749 $ref: '#/components/responses/404'
750 description: Unregister a service
752 - Service Registry and Supervision
756 description: List of service information
759 - callbackUrl: callbackUrl
761 keepAliveIntervalSeconds: 0
762 timeSinceLastActivitySeconds: 6
763 - callbackUrl: callbackUrl
765 keepAliveIntervalSeconds: 0
766 timeSinceLastActivitySeconds: 6
768 description: Status for one A1-P Policy
770 lastModified: last_modified
818 RanUeId: 'a31c510b20e64a74'
835 PolicyTypeInformation:
837 Available policy types and for each policy type identifier the Near-RT
838 RIC identifiers of those Near-RT RICs that support the related A1 policy
843 description: Identity of the policy type
846 $ref: '#/components/schemas/NearRtRicId'
850 PolicyObjectInformation:
851 description: Information related to the creation of the policy
855 description: identity of the target Near-RT RIC
861 description: "if true, the policy is deleted at RIC restart. If false, its\
862 \ value is maintained by this service until explicitly deleted. Default\
867 description: identity of the Policy
872 description: the identity of the service owning the policy. This can be
873 used to group the policies (it is possible to get all policies associated
874 to a service). Note that the service does not need to be registered.
879 $ref: '#/components/schemas/PolicyObject'
880 statusNotificationUri:
881 description: Callback URI for policy status updates
884 description: identity of the policy type
886 example: 'ORAN_QOS_1.0.0(typeName_SemVersion)'
892 description: Problem as defined in https://tools.ietf.org/html/rfc7807
895 description: ' A human-readable explanation specific to this occurrence
897 example: Policy type not found
900 description: 'A specific error name'
904 description: 'The HTTP status code generated by the origin server for this
905 occurrence of the problem. '
911 description: 'Policy Object is a JSON representation of an A1 policy'
914 description: Void/empty
919 description: status text
923 description: Result of authorization
928 description: "If true, the access is granted"
934 description: Information for a Near-RT RIC
937 description: identity of the Near-RT RIC
940 description: O1 identities for managed entities
942 description: O1 identities for managed entities
946 description: Represents the states for a Near-RT RIC
954 description: supported policy types
956 description: supported policy types
960 ServiceRegistrationInfo:
961 description: Information for one service
964 description: callback for notifying of Near-RT RIC state changes
967 description: identity of the service
969 keepAliveIntervalSeconds:
970 description: "keep alive interval for the service. This is used to enable\
971 \ optional heartbeat supervision of the service. If set (> 0) the registered\
972 \ service should regularly invoke a 'keepalive' REST call. When a service\
973 \ fails to invoke this 'keepalive' call within the configured time, the\
974 \ service is considered unavailable. An unavailable service will be automatically\
975 \ deregistered and its policies will be deleted. Value 0 means timeout\
976 \ supervision is disabled."
983 description: Status for one A1-P Policy
986 description: "timestamp, last modification time"
989 description: the Policy status
995 description: callback for notifying of RIC synchronization
998 description: identity of the service
1000 keepAliveIntervalSeconds:
1001 description: policy keep alive timeout
1004 timeSinceLastActivitySeconds:
1005 description: time since last invocation by the service
1010 description: List of Near-RT RIC information
1013 description: List of Near-RT RIC information
1015 $ref: '#/components/schemas/RicInfo'
1022 description: Access type
1029 description: Authorization token
1032 description: Policy type identifier
1039 PolicyAuthorization:
1040 description: Authorization request for A1 policy requests
1043 $ref: '#/components/schemas/input'
1048 description: Identity of the policy
1052 Near-RT RIC identifiers where A1 policies exist and for each Near-RT RIC
1053 identifier the policy identifiers of those policies that exist in that
1058 description: Identity of the policy
1061 $ref: '#/components/schemas/NearRtRicId'
1068 description: List of service information
1070 $ref: '#/components/schemas/ServiceStatus'
1073 ServiceCallbackInfo:
1074 description: Information transferred as in Service callbacks (callback_url)
1077 description: identity of a Near-RT RIC
1080 description: "values:\nAVAILABLE: the Near-RT RIC has become available\
1081 \ for A1 Policy management"
1098 A problem detail to carry details in an HTTP response according to RFC
1104 a URI reference according to IETF RFC 3986 that identifies the
1108 description: human-readable summary of the problem type
1111 description: the HTTP status code
1114 description: 'human-readable explanation '
1117 description: URI reference that identifies the specific occurrence of the problem
1121 description: Bad Request
1123 application/problem+json:
1125 $ref: '#/components/schemas/ProblemDetails'
1127 description: Unauthorized
1129 application/problem+json:
1131 $ref: '#/components/schemas/ProblemDetails'
1133 description: Forbidden
1135 application/problem+json:
1137 $ref: '#/components/schemas/ProblemDetails'
1139 description: Not Found
1141 application/problem+json:
1143 $ref: '#/components/schemas/ProblemDetails'
1145 description: Method Not Allowed
1147 application/problem+json:
1149 $ref: '#/components/schemas/ProblemDetails'
1151 description: Not Acceptable
1153 application/problem+json:
1155 $ref: '#/components/schemas/ProblemDetails'
1157 description: Conflict
1159 application/problem+json:
1161 $ref: '#/components/schemas/ProblemDetails'
1163 description: Length Required
1165 application/problem+json:
1167 $ref: '#/components/schemas/ProblemDetails'
1169 description: Payload Too Large
1171 application/problem+json:
1173 $ref: '#/components/schemas/ProblemDetails'
1175 description: Unsupported Media Type
1177 application/problem+json:
1179 $ref: '#/components/schemas/ProblemDetails'
1181 description: Too Many Request
1183 application/problem+json:
1185 $ref: '#/components/schemas/ProblemDetails'
1187 description: Internal Server Error
1189 application/problem+json:
1191 $ref: '#/components/schemas/ProblemDetails'
1193 description: Bad Gateway
1195 application/problem+json:
1197 $ref: '#/components/schemas/ProblemDetails'
1199 description: Service Unavailable
1201 application/problem+json:
1203 $ref: '#/components/schemas/ProblemDetails'
1205 description: "Locked - HTTP Status code which can be used when the state is Locked"
1207 application/problem+json:
1209 $ref: '#/components/schemas/ErrorInformation'
1213 detail: State is Locked in the provided request.