From 51641945e7c03132eb3664ca379c55ea00d88aa2 Mon Sep 17 00:00:00 2001 From: Teresa Ho Date: Fri, 19 Aug 2022 16:37:18 -0400 Subject: [PATCH] Update REST API doc for PTP notification v2 This commit updates the REST API documentation for PTP notification. Story: 2010056 Task: 46264 Change-Id: I2665d1fcb741ba24bb986d218eb3a537791b1aa2 Signed-off-by: Teresa Ho --- .../api_ptp_notifications_definition_v2.rst | 469 ++++++++++++++++++ api-ref/source/index.rst | 1 + 2 files changed, 470 insertions(+) create mode 100644 api-ref/source/api_ptp_notifications_definition_v2.rst diff --git a/api-ref/source/api_ptp_notifications_definition_v2.rst b/api-ref/source/api_ptp_notifications_definition_v2.rst new file mode 100644 index 0000000..b4dc77e --- /dev/null +++ b/api-ref/source/api_ptp_notifications_definition_v2.rst @@ -0,0 +1,469 @@ +============================================ +PTP Status Notifications API Definition v2 +============================================ + +This document defines how a hosted application can subscribe to receive PTP +status notifications from the StarlingX platform and also how to pull notifications +on demand. + +The interaction between the application and the platform is done with the +use of a Sidecar residing in the same pod. + +The port of the Sidecar is exposed to the application by a downward API and +the address is the localhost of the pod where the application and the Sidecar +are running on. For example: http://127.0.0.1:{port} + +The version 2 of the API is documented in the O-RAN Working Group 6 O-Cloud +Notification API specification for Event Consumers v03.00. +Refer to https://www.o-ran.org/specifications for O-RAN specifications. + +-------------------- +Create Subscription +-------------------- + +As the result of successfully executing this method, a new +subscription resource will be created and a variable value +(subscriptionId) will be used for representing this +resource. An initial PTP notification will be triggered, +showing the initial status of the PTP resource followed +by PTP status notifications if there is a change to the +PTP status. + +************************************************ +Subscribe to receiving PTP status notifications +************************************************ + +.. rest_method:: POST /ocloudNotifications/v2/subscriptions + +**Normal response codes** + +201 + +**Error response codes** + +badRequest (400), itemNotFound (404), conflict(409) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:9090/resourcestatus/ptp" + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "SubscriptionId", "plain", "csapi:UUID", "Identifier for the created subscription resource." + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:9090/resourcestatus/ptp" + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/gnss-status/gnss-sync-status", + "SubscriptionId": "704f21a0-19a3-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/704f21a0-19a3-11ed-854c-8a6cf180560d" + } + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync", + "SubscriptionId": "dcdae0de-19a3-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/dcdae0de-19a3-11ed-854c-8a6cf180560d" + } + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/sync-status/sync-state", + "SubscriptionId": "ca244f8a-1fec-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/ca244f8a-1fec-11ed-854c-8a6cf180560d" + } + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/sync-status/os-clock-sync-state", + "SubscriptionId": "8ded8d18-1fee-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/8ded8d18-1fee-11ed-854c-8a6cf180560d" + } + +---------------------- +Manage Subscriptions +---------------------- + +****************************** +Query subscription resources +****************************** + +.. rest_method:: GET /ocloudNotifications/v2/subscriptions + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (404) + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "SubscriptionId", "plain", "csapi:UUID", "Identifier for the created subscription resource." + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:9090/resourcestatus/ptp" + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/gnss-status/gnss-sync-status", + "SubscriptionId": "704f21a0-19a3-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/704f21a0-19a3-11ed-854c-8a6cf180560d" + } + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/sync-status/sync-state", + "SubscriptionId": "ca244f8a-1fec-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/ca244f8a-1fec-11ed-854c-8a6cf180560d" + } + +This operation does not accept a request body. + +**************************************** +Query individual subscription resource +**************************************** + +.. rest_method:: GET /ocloudNotifications/v2/{SubscriptionId} + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "SubscriptionId", "plain", "csapi:UUID", "Identifier for the created subscription resource." + +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "SubscriptionId", "plain", "csapi:UUID", "Identifier for the created subscription resource." + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:9090/resourcestatus/ptp" + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v2/resource_status/ptp", + "ResourceAddress": "/./controller-0/sync/sync-status/os-clock-sync-state", + "SubscriptionId": "8ded8d18-1fee-11ed-854c-8a6cf180560d", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v2/subscriptions/8ded8d18-1fee-11ed-854c-8a6cf180560d" + } + +This operation does not accept a request body + +**************************************** +Delete individual subscription resource +**************************************** + +.. rest_method:: DELETE /ocloudNotifications/v2/{SubscriptionId} + +**Normal response codes** + +204 + +**Error response codes** + +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "SubscriptionId", "plain", "csapi:UUID", "Identifier for the created subscription resource." + +This operation does not accept a request body. + +-------------------------- +Pull Status Notifications +-------------------------- + +****************************** +Pull PTP status notifications +****************************** + +.. rest_method:: GET /ocloudNotifications/v2/{ResourceAddress}/CurrentState + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported. PTP instance name is supported." + +This operation does not accept a request body. +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "id", "plain", "xsd:string", "Identifies the event." + "specversion", "plain", "xsd:string", "The version of the CloudEvents specification which the event uses. This enables the interpretation of the context." + "source", "plain", "xsd:string", "Identifies the context in which an event happened." + "type", "plain", "xsd:string", "This attribute contains a value describing the type of event related to the originating occurrence." + "time", "plain", "xsd:string", "Time at which the event occurred." + "data", "plain", "xsd:string", "Array of JSON objects defining the information for the event" + "version", "plain", "xsd:string", "Version of the Notification API Schema generating the event." + "values", "plain", "xsd:string", "A JSON array of values defining the event." + "data_type", "plain", "xsd:string", "Type of value object. (notification | metric)" + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "value_type", "plain", "xsd:string", "The type format of the value property (enumeration or metric)" + "value", "plain", "xsd:string", "String representation of value in value_type format" + +:: + + { + "id": "d38af5a6-70bb-4b3d-892a-df50cf2fdb09", + "specversion": "1.0", + "source": "/sync/sync-status/sync-state", + "type": "event.sync.sync-status.synchronization-state-change", + "time": "2022-08-12T19:20:54896244Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/sync-status/sync-state", + "value_type": "enumeration", + "value": "Locked" + } + ] + } + } + +:: + + { + "ptp-inst1": { + "id": "0088ea9e-ba57-409c-bfcb-8163e5c39c70", + "specversion": "1.0", + "source": "/sync/ptp-status/clock-class", + "type": "event.sync.ptp-status.ptp-clock-class-change", + "time": "2022-09-09T15:57:40078935Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "metric", + "ResourceAddress": "/././sync/ptp-status/clock-class", + "value_type": "metric", + "value": "6" + } + ] + } + } + } + +:: + + { + "ptp-inst1": { + "id": "ee37956c-5fed-4414-abce-d8de44fa6718", + "specversion": "1.0", + "source": "/sync/ptp-status/lock-state", + "type": "event.sync.ptp-status.ptp-state-change", + "time": "2022-09-09T15:57:40078919Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/ptp-status/lock-state", + "value_type": "enumeration", + "value": "Locked" + } + ] + } + } + } + +:: + + { + "os_clock_status": { + "id": "404631ea-8011-4dd1-bd46-cf97ddc1d6d0", + "specversion": "1.0", + "source": "/sync/sync-status/os-clock-sync-state", + "type": "event.sync.sync-status.os-clock-sync-state-change", + "time": "2022-09-09T15:57:46020908Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/sync-status/os-clock-sync-state", + "value_type": "enumeration", + "value": "Locked" + } + ] + } + } + } + +:: + + { + "overall_sync_status": { + "id": "a7139f82-0a13-4c33-b7b5-b4773def1377", + "specversion": "1.0", + "source": "/sync/sync-status/sync-state", + "type": "event.sync.sync-status.synchronization-state-change", + "time": "2022-09-09T15:57:46034060Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/sync-status/sync-state", + "value_type": "enumeration", + "value": "Locked" + } + ] + } + } + } + +:: + + { + "ts1": { + "id": "230f4f09-d5ba-4c82-966b-52f7f3c22e14", + "specversion": "1.0", + "source": "/sync/gnss-status/gnss-sync-status", + "type": "event.sync.gnss-status.gnss-state-change", + "time": "2022-09-12T14:31:45519571Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/gnss-status/gnss-sync-status", + "value_type": "enumeration", + "value": "Locked" + } + ] + } + } + } + + +This operation does not accept a request body. + +-------------------- +Push Notifications +-------------------- + +After a successful subscription (a subscription resource was created) +the application (e.g. vDU) will be able to receive PTP status notifications. +Note that notifications are sent to the application when there is a change +to the PTP synchronization state. + +The notification will be sent to the endpoint reference (EndpointUri) provided +by the application during the creation of the subscription resource. +StarlingX platform includes the notification data in the payload body of +the POST request to the application's EndpointURI (http://127.0.0.1:{port}/{path}). + +************************************************************ +Send PTP status notifications to the application subscribed +************************************************************ + +.. rest_method:: POST {CallbackUri} + +**Normal response codes** + +204 + +**Error response codes** + +badRequest (400), itemNotFound (404), tiemout(408) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "id", "plain", "xsd:string", "Identifies the event." + "specversion", "plain", "xsd:string", "The version of the CloudEvents specification which the event uses. This enables the interpretation of the context." + "source", "plain", "xsd:string", "Identifies the context in which an event happened." + "type", "plain", "xsd:string", "This attribute contains a value describing the type of event related to the originating occurrence." + "time", "plain", "xsd:string", "Time at which the event occurred." + "data", "plain", "xsd:string", "Array of JSON objects defining the information for the event." + "version", "plain", "xsd:string", "Version of the Notification API Schema generating the event." + "values", "plain", "xsd:string", "A JSON array of values defining the event." + "data_type", "plain", "xsd:string", "Type of value object. (notification | metric)" + "ResourceAddress", "plain", "xsd:string", "Specifies a hierarchical path which consists of the resource. Only the current cluster and node is supported." + "value_type", "plain", "xsd:string", "The type format of the value property (enumeration or metric)" + "value", "plain", "xsd:string", "String representation of value in value_type format." + +:: + + { + "id": "d38af5a6-70bb-4b3d-892a-df50cf2fdb09", + "specversion": "1.0", + "source": "/sync/sync-status/sync-state", + "type": "event.sync.sync-status.synchronization-state-change", + "time": "2022-08-12T19:20:54896244Z", + "data": { + "version": "1.0", + "values": [ + { + "data_type": "notification", + "ResourceAddress": "/././sync/sync-status/sync-state", + "value_type": "enumeration", + "value": "Holdover" + } + ] + } + } + diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 9d6d977..8a57310 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -13,3 +13,4 @@ API definition :maxdepth: 2 api_ptp_notifications_definition_v1 + api_ptp_notifications_definition_v2