diff options
Diffstat (limited to 'docs/offeredapis')
| -rw-r--r-- | docs/offeredapis/offeredapis.rst | 9 | ||||
| -rw-r--r-- | docs/offeredapis/swagger/pms-api.yaml | 842 |
2 files changed, 848 insertions, 3 deletions
diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst index 7d32acb4..c3a7c95f 100644 --- a/docs/offeredapis/offeredapis.rst +++ b/docs/offeredapis/offeredapis.rst @@ -68,12 +68,15 @@ API Table .. |swagger-icon| image:: ../media/swagger.png :width: 40px +.. |yaml-icon| image:: ../media/yaml_logo.png + :width: 40px + .. csv-table:: - :header: "API name", "|swagger-icon|" - :widths: 10,5 + :header: "API name", "|swagger-icon|", "|yaml-icon|" + :widths: 10,5, 5 - "PMS API", ":download:`link <./swagger/pms-api.json>`" + "PMS API", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`" .. _pms_api: diff --git a/docs/offeredapis/swagger/pms-api.yaml b/docs/offeredapis/swagger/pms-api.yaml new file mode 100644 index 00000000..ac10f4b6 --- /dev/null +++ b/docs/offeredapis/swagger/pms-api.yaml @@ -0,0 +1,842 @@ +openapi: 3.0.1 +info: + 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" +servers: +- url: https://localhost:8433/ +- url: http://localhost:8081/ +tags: +- name: A1 Policy Management + description: Policy Controller +- name: Health check + description: Status Controller +- name: RIC Repository + description: Ric Repository Controller +- name: Service registry and supervision + description: Service Controller +paths: + /policies: + get: + tags: + - A1 Policy Management + summary: Query policies + operationId: getPoliciesUsingGET + parameters: + - name: ric + in: query + description: The name of the Near-RT RIC to get policies for. + allowEmptyValue: false + schema: + type: string + example: 'ric1' + - name: service + in: query + description: The name of the service to get policies for. + allowEmptyValue: false + schema: + type: string + example: 'controlpanel' + - name: type + in: query + description: The name of the policy type to get policies for. + allowEmptyValue: false + schema: + type: string + example: '1' + responses: + 200: + description: Policies + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + items: + $ref: '#/components/schemas/PolicyInfo' + examples: + OSC: + $ref: '#/components/examples/Policies-OSC' + STD: + $ref: '#/components/examples/Policies-STD' + 404: + description: RIC or type not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: RIC not found + deprecated: false + /policy: + get: + tags: + - A1 Policy Management + summary: Returns a policy configuration + operationId: getPolicyUsingGET + parameters: + - name: id + in: query + description: The identity of the policy instance. + required: true + allowEmptyValue: false + schema: + type: string + example: 'e26d76e1-b43f-427e-a3c2-b7c4e05a6431' + responses: + 200: + description: Policy found + content: + text/plain;charset=ISO-8859-1: + schema: + type: object + examples: + OSC: + $ref: '#/components/examples/Policy-OSC' + STD: + $ref: '#/components/examples/Policy-STD' + 404: + description: Policy is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Could not find policy: e26d76e1-b43f-427e-a3c2-b7c4e05a6431' + deprecated: false + put: + tags: + - A1 Policy Management + summary: Put a policy + operationId: putPolicyUsingPUT + parameters: + - name: id + in: query + description: The identity of the policy instance. + required: true + allowEmptyValue: false + schema: + type: string + example: '73428e58-1670-4972-8498-e7e8f1003631' + - name: ric + in: query + description: The name of the Near-RT RIC where the policy will be created. + required: true + allowEmptyValue: false + schema: + type: string + example: 'ric1' + - name: service + in: query + description: The name of the service creating the policy. + required: true + allowEmptyValue: false + schema: + type: string + example: 'Service1' + - name: transient + in: query + description: If the policy is transient or not (boolean defaulted to false). + A policy is transient if it will be forgotten when the service needs to + reconnect to the Near-RT RIC. + allowEmptyValue: false + schema: + type: boolean + default: false + example: false + - name: type + in: query + description: The name of the policy type. The policy type is mandatory for OSC A1 version and should not be provided for STD A1 version. + allowEmptyValue: false + schema: + type: string + example: 'STD_PolicyModelUnconstrained_0.2.0' + requestBody: + description: jsonBody + content: + application/json: + schema: + type: object + example: + scope: + qosId: "3" + ueId: "1" + statement: + priorityLevel: 1 + required: true + responses: + 200: + description: Policy updated + 201: + description: Policy created + 404: + description: RIC or policy type is not found + 423: + description: RIC is not operational + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Ric is not operational, RIC name:ric1, state:UNAVAILABLE' + delete: + tags: + - A1 Policy Management + summary: Delete a policy + operationId: deletePolicyUsingDELETE + parameters: + - name: id + in: query + description: The identity of the policy instance. + required: true + allowEmptyValue: false + schema: + type: string + example: '73428e58-1670-4972-8498-e7e8f1003631' + responses: + 200: + description: OK + 204: + description: Policy deleted + 404: + description: Policy is not found + 423: + description: RIC is not operational + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Ric is not operational, RIC name:ric1,state:UNAVAILABLE' + deprecated: false + /policy_ids: + get: + tags: + - A1 Policy Management + summary: Query policies, only IDs returned + operationId: getPolicyIdsUsingGET + parameters: + - name: ric + in: query + description: The name of the Near-RT RIC to get policies for. + allowEmptyValue: false + schema: + type: string + example: 'ric1' + - name: service + in: query + description: The name of the service to get policies for. + allowEmptyValue: false + schema: + type: string + example: 'Service1' + - name: type + in: query + description: The name of the policy type to get policies for. + allowEmptyValue: false + schema: + type: string + example: '1' + responses: + 200: + description: Policy ids + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + items: + type: string + examples: + OSC: + value: + - 73428e58-1670-4972-8498-e7e8f1003631 + - 73428e58-1670-4972-8498-e7e8f100363e + STD: + value: + - 73428e58-1670-4972-8498-e7e8f1003632 + - 73428e58-1670-4972-8498-e7e8f1003634 + 404: + description: RIC or type not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: RIC not found + deprecated: false + /policy_schema: + get: + tags: + - A1 Policy Management + summary: Returns one policy type schema definition. Applicable only for OSC Version. + operationId: getPolicySchemaUsingGET + parameters: + - name: id + in: query + description: The identity of the policy type to get the definition for. + required: true + allowEmptyValue: false + schema: + type: string + example: '11' + responses: + 200: + description: Policy schema + content: + text/plain;charset=ISO-8859-1: + schema: + type: object + examples: + OSC: + value: + $schema: http://json-schema.org/draft-07/schema# + description: QoS policy type + title: "1" + type: object + properties: + scope: + additionalProperties: false + type: object + properties: + qosId: + type: string + ueId: + type: string + required: + - ueId + - qosId + statement: + additionalProperties: false + type: object + properties: + priorityLevel: + type: number + required: + - priorityLevel + 404: + description: Type not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'org.oransc.policyagent.exceptions.ServiceException: Could + not find type: 11' + deprecated: false + /policy_schemas: + get: + tags: + - A1 Policy Management + summary: Returns policy type schema definitions + operationId: getPolicySchemasUsingGET + parameters: + - name: ric + in: query + description: The name of the Near-RT RIC to get the definitions for. + allowEmptyValue: false + schema: + type: string + example: ric1 + responses: + 200: + description: Policy schemas + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + items: + type: object + properties: {} + examples: + OSC: + value: + - $schema: http://json-schema.org/draft-07/schema# + description: QoS policy type + title: "1" + type: object + properties: + scope: + additionalProperties: false + type: object + properties: + qosId: + type: string + ueId: + type: string + required: + - ueId + - qosId + statement: + additionalProperties: false + type: object + properties: + priorityLevel: + type: number + required: + - priorityLevel + 404: + description: RIC is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'org.oransc.policyagent.exceptions.ServiceException: Could + not find ric: ric1' + deprecated: false + /policy_status: + get: + tags: + - A1 Policy Management + summary: Returns a policy status + operationId: getPolicyStatusUsingGET + parameters: + - name: id + in: query + description: The identity of the policy. + required: true + allowEmptyValue: false + schema: + type: string + example: 73428e58-1670-4972-8498-e7e8f100363q + responses: + 200: + description: Policy status + content: + text/plain;charset=ISO-8859-1: + schema: + type: object + examples: + OSC: + value: + instance_status: NOT IN EFFECT + has_been_deleted: "false" + created_at: 07/20/2020, 17:15:39 + STD: + value: + enforceStatus: UNDEFINED + 404: + description: Policy is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Could not find policy: 73428e58-1670-4972-8498-e7e8f100363q' + deprecated: false + /policy_types: + get: + tags: + - A1 Policy Management + summary: Query policy type names + operationId: getPolicyTypesUsingGET + parameters: + - name: ric + in: query + description: The name of the Near-RT RIC to get types for. + allowEmptyValue: false + schema: + type: string + example: 'ric11' + responses: + 200: + description: Policy type names + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + items: + type: string + examples: + OSC: + value: + - "1" + 404: + description: RIC is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'org.oransc.policyagent.exceptions.ServiceException: Could + not find ric: ric11' + deprecated: false + /ric: + get: + tags: + - RIC Repository + summary: Returns the name of a RIC managing one Mananged Element + operationId: getRicUsingGET + parameters: + - name: managedElementId + in: query + description: The identity of the Managed Element + required: true + allowEmptyValue: false + schema: + type: string + example: 'Node 1' + responses: + 200: + description: RIC is found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: ric1 + 404: + description: RIC is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: No RIC found + deprecated: false + /rics: + get: + tags: + - RIC Repository + summary: Query Near-RT RIC information + operationId: getRicsUsingGET + parameters: + - name: policyType + in: query + description: The name of the policy type + allowEmptyValue: false + schema: + type: string + example: 'STD_PolicyModelUnconstrained_0.2.0' + responses: + 200: + description: OK + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + items: + $ref: '#/components/schemas/RicInfo' + 404: + description: Policy type is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: Policy type not found + deprecated: false + /service: + put: + tags: + - Service registry and supervision + summary: Register a service + operationId: putServiceUsingPUT + requestBody: + description: registrationInfo + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceRegistrationInfo' + required: true + responses: + 200: + description: Service updated + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: OK + 201: + description: Service created + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: OK + 400: + description: The ServiceRegistrationInfo is not accepted + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: Missing mandatory parameter 'serviceName' + 404: + description: Not Found + deprecated: false + x-codegen-request-body-name: registrationInfo + /services: + get: + tags: + - Service registry and supervision + summary: Returns service information + operationId: getServicesUsingGET + parameters: + - name: name + in: query + description: The name of the service + allowEmptyValue: false + schema: + type: string + example: 'service1' + responses: + 200: + description: OK + content: + text/plain;charset=ISO-8859-1: + schema: + type: array + example: + - serviceName: "service1" + keepAliveIntervalSeconds: 1000 + timeSinceLastActivitySeconds: 7 + callbackUrl: http://localhost:8080 + items: + $ref: '#/components/schemas/ServiceStatus' + 404: + description: Service is not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: Service not found + deprecated: false + delete: + tags: + - Service registry and supervision + summary: Delete a service + operationId: deleteServiceUsingDELETE + parameters: + - name: name + in: query + description: The name of the service + required: true + allowEmptyValue: false + schema: + type: string + example: 'service1' + responses: + 200: + description: OK + 204: + description: OK + 404: + description: Service not found + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Could not find service: service1' + deprecated: false + /services/keepalive: + put: + tags: + - Service registry and supervision + summary: Heartbeat from a serice + operationId: keepAliveServiceUsingPUT + parameters: + - name: name + in: query + description: The name of the service + required: true + allowEmptyValue: false + schema: + type: string + example: 'service1' + responses: + 200: + description: Service supervision timer refreshed, OK + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: OK + 201: + description: Created + 404: + description: The service is not found, needs re-registration + content: + text/plain;charset=ISO-8859-1: + schema: + type: string + example: 'Could not find service: service1' + deprecated: false + /status: + get: + tags: + - Health check + summary: Returns status and statistics of this service + operationId: getStatusUsingGET + responses: + 200: + description: Service is living + content: + '*/*': + schema: + type: string + example: alive + 404: + description: Not Found + deprecated: false +components: + schemas: + PolicyInfo: + title: PolicyInfo + type: object + properties: + id: + type: string + description: identity of the policy + json: + type: object + properties: {} + description: the configuration of the policy + lastModified: + type: string + description: timestamp, last modification time + ric: + type: string + description: identity of the target Near-RT RIC + service: + type: string + description: the name of the service owning the policy + type: + type: string + description: name of the policy type + RicInfo: + title: RicInfo + type: object + properties: + managedElementIds: + type: array + description: O1 identities for managed entities + items: + type: string + policyTypes: + type: array + description: supported policy types + items: + type: string + ricName: + type: string + description: identity of the ric + state: + type: string + description: state info + example: + - ricName: ric1 + managedElementIds: + - ME-1 + - ME-2 + policyTypes: + - '1' + state: AVAILABLE + - ricName: ric3 + managedElementIds: + - ME-1 + - ME-2 + policyTypes: + - '' + state: AVAILABLE + - ricName: ric2 + managedElementIds: + - ME-1 + - ME-2 + policyTypes: [] + state: AVAILABLE + - ricName: ric4 + managedElementIds: + - ME-1 + - ME-2 + policyTypes: + - '' + state: AVAILABLE + ServiceRegistrationInfo: + title: ServiceRegistrationInfo + required: + - serviceName + type: object + properties: + callbackUrl: + type: string + description: callback for notifying of RIC synchronization + 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. + format: int64 + serviceName: + type: string + description: identity of the service + example: + callbackUrl: http://localhost:9080 + keepAliveIntervalSeconds: 1000 + serviceName: service1 + ServiceStatus: + title: ServiceStatus + type: object + properties: + callbackUrl: + type: string + description: callback for notifying of RIC synchronization + keepAliveIntervalSeconds: + type: integer + description: policy keep alive timeout + format: int64 + serviceName: + type: string + description: identity of the service + timeSinceLastActivitySeconds: + type: integer + description: time since last invocation by the service + format: int64 + examples: + Policies-STD: + value: + - id: a986eb38-aac3-4897-bdf5-0333ea2bf730 + type: '' + ric: ric3 + json: + scope: + ueId: ue1 + groupId: group1 + sliceId: slice1 + qosId: qos1 + cellId: cell1 + statement: + priorityLevel: 5 + service: controlpanel + lastModified: '2020-07-22T12:21:48.157854Z' + Policies-OSC: + value: + - id: 73428e58-1670-4972-8498-e7e8f1003631 + type: '1' + ric: ric1 + json: + scope: + qosId: '36' + ueId: '1' + statement: + priorityLevel: 1 + service: c + lastModified: '2020-07-20T17:16:18.244383Z' + - id: 73428e58-1670-4972-8498-e7e8f100363e + type: '1' + ric: ric1 + json: + scope: + qosId: '34' + ueId: '1' + statement: + priorityLevel: 1 + service: controlpanel + lastModified: '2020-07-20T17:15:39.320469Z' + Policy-STD: + value: + scope: + ueId: ue1 + groupId: group1 + sliceId: slice1 + qosId: qos1 + cellId: cell1 + statement: + priorityLevel: 5 + Policy-OSC: + value: + scope: + qosId: '36' + ueId: '1' + statement: + priorityLevel: 1
\ No newline at end of file |