diff options
Diffstat (limited to 'docs/offeredapis')
| -rw-r--r-- | docs/offeredapis/offeredapis.rst | 62 | ||||
| -rw-r--r-- | docs/offeredapis/swagger/pms-api.json | 12 | ||||
| -rw-r--r-- | docs/offeredapis/swagger/pms-api.yaml | 36 |
3 files changed, 52 insertions, 58 deletions
diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst index b6b2cd66..99f59e9b 100644 --- a/docs/offeredapis/offeredapis.rst +++ b/docs/offeredapis/offeredapis.rst @@ -1,7 +1,7 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2020 Nordix Foundation +.. Copyright 2021 Nordix Foundation .. _offered_apis: @@ -10,54 +10,22 @@ Offered APIs ============ Introduction -************ +------------ -The north bound REST API of the Policy Management Service provides convenient methods to handle policies. +The north bound REST API of the A1 Policy Management Service provides convenient methods to handle policies. -Global ORAN architecture -************************ +Overall architecture for O-RAN A1 Policy functions +-------------------------------------------------- -Following illustration provides a global view about **ORAN** architecture, +This picture provides a overview of ONAP's A1 Controller architecture, integration with other ONAP components and API resource/operation provided. .. image:: ../media/ONAP-A1ControllerArchitecture.png :width: 500pt - -API Version -*********** - -APIs are described with a state version with "v" following the API Name, -e.g.: ``v2/policy``. -The schema associated with a REST API must have its version number aligned -with that of the REST API. - -The version number has major, minor and revision numbers. E.g. v1.0.0 -The version number (without the revision number) is held in the URI. - -The major version number is incremented for an incompatible change. -The minor version number is incremented for a compatible change. -For minor modifications of the API, version numbering must not be updated, -provided the following backward compatibility rules are respected: - -- New elements in a data type must be optional (``minOccurs=0``) -- Changes in the cardinality of an attribute in a data type must be from - mandatory to optional or from lower to greater -- New attributes defined in an element must be optional (absence of - ``use="required"``). -- If new enumerated values are included, the former ones and its meaning must - be kept. -- If new operations are added, the existing operations must be kept -- New parameters added to existing operations must be optional and existing - parameters must be kept - -For major modifications of the API, not backward compatible and forcing client -implementations to be changed, the version number must be updated. - - API Table -********* +--------- .. |swagger-icon| image:: ../media/swagger.png :width: 40px @@ -70,19 +38,23 @@ API Table :header: "API name", "|swagger-icon|", "|yaml-icon|" :widths: 10,5, 5 - "PMS API", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`" + "A1 Policy Management Service API (NBI)", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`" "A1 ADAPTER API (Internal)", ":download:`link <./swagger/a1-adapter-api.json>`", ":download:`link <./swagger/a1-adapter-api.yaml>`" - .. _pms_api: -PMS API -....... -`PMS API <./pms-api.html>`_ +A1 Policy Management Service API +................................ + +The A1 Policy Management Service API is described in more detail in `A1 Policy Management Service API (html) <./pms-api.html>`_ + .. _a1_adapter_api: A1 ADAPTER API .............. -`A1 ADAPTER API (Internal) <./a1-adapter-api.html>`_ + +The O-RAN A1 Adapter provides an **internal** RESTCONF API that is used by the A1 Policy Management System when accessing the A1 Interface. This API is useful for test and verification but should not be used otherwise. + +The A1 Adapter API is described in more detail in `A1 ADAPTER API (html) <./a1-adapter-api.html>`_ diff --git a/docs/offeredapis/swagger/pms-api.json b/docs/offeredapis/swagger/pms-api.json index 1837e098..72eaa977 100644 --- a/docs/offeredapis/swagger/pms-api.json +++ b/docs/offeredapis/swagger/pms-api.json @@ -1,7 +1,7 @@ { "openapi": "3.0.1", "info": { - "title": "A1 Policy management service", + "title": "A1 Policy Management Service", "description": "The O-RAN Non-RT RIC PolicyAgent provides a REST API for management of policices. It provides support for: -Supervision of clients (R-APPs) to eliminate stray policies in case of failure -Consistency monitoring of the SMO view of policies and the actual situation in the RICs -Consistency monitoring of RIC capabilities (policy types) -Policy configuration. This includes: -One REST API towards all RICs in the network -Query functions that can find all policies in a RIC, all policies owned by a service (R-APP), all policies of a type etc. -Maps O1 resources (ManagedElement) as defined in O1 to the controlling RIC of A1 policices.", "version": "1.0" }, @@ -16,19 +16,19 @@ "tags": [ { "name": "A1 Policy Management", - "description": "Policy Controller" + "description": "This is the north bound API of the A1 Policy Management Service (\"Policy Agent\"). This API allows *services* to interact with the Policy Agent using REST. By registering with the Policy Agent, the Policy Agent takes responsibility for synchronizing the policies created by the service in the Near RT RICs. This means that if a Near RT RIC restarts, the Policy Agent will try to recreate all the policies residing in the Near RT RIC once it is started again. If this is not possible, it will remove all policies belonging to the Near RT RIC. The Policy Agent also keeps an updated view of the policy types available, and which Near RT RICs that support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain Near RT RIC." }, { "name": "Health check", - "description": "Status Controller" + "description": "The status of the A1 Policy Management Service" }, { "name": "RIC Repository", - "description": "Ric Repository Controller" + "description": "The A1 Policy Management Service keeps an updated view of the Near RT RICs that are available in the system. A service can find out which Near RT RIC that manages a specific element in the network or which Near RT RICs that support a specific policy type." }, { "name": "Service registry and supervision", - "description": "Service Controller" + "description": "A service can register itself in the A1 Policy Management Service. By providing a callback URL the service can get notifications from the A1 Policy Management Service. A service can also register a \"*Keep Alive Interval*\", in seconds. By doing this the service promises to call the A1 Policy Management Service's \"*Keep Alive*\" method, or else create or delete policies, more often than the \"*Keep Alive Interval*\" measured in seconds. If the service, for some reason, is not able to do this, the A1 Policy Management Service will consider that the service has died or vanished and will then delete all its policies, both in the internal repository and in the Near RT RICs where they were earlier created. **Note!** If the service does not provide a value for \"*Keep Alive Interval*\", then the service maintains full responsibility to delete all of its policies when they are no longer needed." } ], "paths": { @@ -1130,7 +1130,7 @@ }, "keepAliveIntervalSeconds": { "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.", + "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" }, "serviceName": { diff --git a/docs/offeredapis/swagger/pms-api.yaml b/docs/offeredapis/swagger/pms-api.yaml index 3bf13a21..865eb770 100644 --- a/docs/offeredapis/swagger/pms-api.yaml +++ b/docs/offeredapis/swagger/pms-api.yaml @@ -1,7 +1,7 @@ --- openapi: 3.0.1 info: - title: A1 Policy management service + title: A1 Policy Management Service description: 'The O-RAN Non-RT RIC PolicyAgent provides a REST API for management of policices. It provides support for: -Supervision of clients (R-APPs) to eliminate stray policies in case of failure -Consistency monitoring of the SMO view of policies @@ -16,13 +16,36 @@ servers: - url: http://localhost:8081/ tags: - name: A1 Policy Management - description: Policy Controller + description: This is the north bound API of the A1 Policy Management Service ("Policy + Agent"). This API allows *services* to interact with the Policy Agent using REST. + By registering with the Policy Agent, the Policy Agent takes responsibility for + synchronizing the policies created by the service in the Near RT RICs. This means + that if a Near RT RIC restarts, the Policy Agent will try to recreate all the + policies residing in the Near RT RIC once it is started again. If this is not + possible, it will remove all policies belonging to the Near RT RIC. The Policy + Agent also keeps an updated view of the policy types available, and which Near + RT RICs that support which types. Also, the Policy Agent can tell if a Managed + Element is managed by a certain Near RT RIC. - name: Health check - description: Status Controller + description: The status of the A1 Policy Management Service - name: RIC Repository - description: Ric Repository Controller + description: The A1 Policy Management Service keeps an updated view of the Near + RT RICs that are available in the system. A service can find out which Near RT + RIC that manages a specific element in the network or which Near RT RICs that + support a specific policy type. - name: Service registry and supervision - description: Service Controller + description: A service can register itself in the A1 Policy Management Service. + By providing a callback URL the service can get notifications from the A1 Policy + Management Service. A service can also register a "*Keep Alive Interval*", in + seconds. By doing this the service promises to call the A1 Policy Management Service's + "*Keep Alive*" method, or else create or delete policies, more often than the + "*Keep Alive Interval*" measured in seconds. If the service, for some reason, + is not able to do this, the A1 Policy Management Service will consider that the + service has died or vanished and will then delete all its policies, both in the + internal repository and in the Near RT RICs where they were earlier created. **Note!** + If the service does not provide a value for "*Keep Alive Interval*", then the + service maintains full responsibility to delete all of its policies when they + are no longer needed. paths: "/policies": get: @@ -759,7 +782,7 @@ components: description: callback for notifying of RIC synchronization keepAliveIntervalSeconds: type: integer - description: keep alive interval for the service. This is a heartbeat supervision + 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 @@ -849,4 +872,3 @@ components: ueId: '1' statement: priorityLevel: 1 - |