From 0a840ffe3744802d69f3292ac922d2afffa621ca Mon Sep 17 00:00:00 2001 From: Udi Schwager Date: Fri, 26 Feb 2021 19:53:15 -0500 Subject: [PATCH] Add PTP Notification API definitions spec The communication between the Sidecar and the application is done via a REST API. This document defines the API and data model. Story: 2008529 Task: 41943 Signed-off-by: Udi Schwager Change-Id: I8eed27322433f565c66c1a566ac8bbef0b8903b8 --- .../api_ptp_notifications_definition_v1.rst | 315 ++++++++++++++++++ api-ref/source/conf.py | 64 ++++ api-ref/source/index.rst | 14 + 3 files changed, 393 insertions(+) create mode 100644 api-ref/source/api_ptp_notifications_definition_v1.rst create mode 100644 api-ref/source/conf.py create mode 100644 api-ref/source/index.rst diff --git a/api-ref/source/api_ptp_notifications_definition_v1.rst b/api-ref/source/api_ptp_notifications_definition_v1.rst new file mode 100644 index 0000000..a7af3e9 --- /dev/null +++ b/api-ref/source/api_ptp_notifications_definition_v1.rst @@ -0,0 +1,315 @@ +============================================ +PTP Status Notifications API Definition v1 +============================================ + +This document defines how an hosted application can subscribe for receving PTP +status notifications from 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, resides in the same pod. + +The port of the Sidecar is exposed to the application by a downward API and +the address is localhost of the pod where the application and the Sidecar +are running on. For example: http://127.0.0.1:{port} + +-------------------- +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/v1/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 + + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides: ``*`` for all worker nodes, ``.`` for worker node where the application resides, node name specified by the downward API" + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:8080/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." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:8080/resourcestatus/ptp" + +:: + + { + "ResourceType": "PTP", + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp" + } + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp", + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "ResourceType": "PTP", + "SubscriptionId": "a904a444-7e30-11eb-9fd0-82e7589e5f61", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/a904a444-7e30-11eb-9fd0-82e7589e5f61" + } + +---------------------- +Manange Subscriptions +---------------------- + +****************************** +Query subscription resources +****************************** + +.. rest_method:: rest_method:: GET /ocloudNotifications/v1/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." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:8080/resourcestatus/ptp" + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp", + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "ResourceType": "PTP", + "SubscriptionId": "a904a444-7e30-11eb-9fd0-82e7589e5f61", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/a904a444-7e30-11eb-9fd0-82e7589e5f61" + } + + { + "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp_cluster", + "ResourceQualifier": { + "NodeName": "*" + }, + "ResourceType": "PTP", + "SubscriptionId": "e614a666-7e30-11eb-9fd0-2e87589e8a30", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/e614a666-7e30-11eb-9fd0-2e87589e8a30" + } + +This operation does not accept a request body. + +**************************************** +Query individual subscription resource +**************************************** + +.. rest_method:: rest_method:: GET /ocloudNotifications/v1/{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." + "UriLocation", "plain", "xsd:string", "The URI location to query the subscription resource created." + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" + "EndpointUri", "plain", "xsd:string", "Endpoint URI (a.k.a callback URI), e.g. http://127.0.0.1:8080/resourcestatus/ptp" + +:: + + { + "EndpointUri": "http://127.0.0.1:9090/v1/resource_status/ptp", + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "ResourceType": "PTP", + "SubscriptionId": "a904a444-7e30-11eb-9fd0-82e7589e5f61", + "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/a904a444-7e30-11eb-9fd0-82e7589e5f61" + } + +This operation does not accept a request body + +**************************************** +Delete individual subscription resource +**************************************** + +.. rest_method:: rest_method:: DELETE /ocloudNotifications/v1/{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:: rest_method:: GET /ocloudNotifications/{ResourceType}/CurrentState + +**Normal response codes** + +200 + +**Error response codes** + +itemNotFound (404) + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + +This operation does not accept a request body. +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "EventData", "plain", ""xsd:string, "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." + "EventTimestamp", "plain", "xsd:float", "This is the time that the event was detected (elapsed seconds since epoch time)." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + +:: + + { + "EventData": { + "State": "Freerun" + }, + "EventTimestamp": 1614969298.8842714, + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "ResourceType": "PTP" + } + +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 {EndpointUri} + +**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 + + "EventData", "plain", ""xsd:string, "Describes the synchronization state for PTP, State: ``Freerun``, ``Locked``, ``Holdover``." + "EventTimestamp", "plain", "xsd:float", "This is the time that the event was detected (elapsed seconds since epoch time)." + "ResourceQualifier", "plain", "xsd:string", "The node name where PTP resides, ``NodeName``: ``*`` for all worker nodes, ``.`` for worker node where the application resides, ``node name`` specified by the downward API" + "ResourceType", "plain", "xsd:string", "The resource to subscribe to, currently only ``PTP`` is supported." + +:: + + { + "EventData": { + "State": "Holdover" + }, + "EventTimestamp": 1714929761.8942328, + "ResourceQualifier": { + "NodeName": "controller-0" + }, + "ResourceType": "PTP" + } diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 0000000..e953e5d --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,64 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# stx-config API reference documentation build configuration file +# +# This file is execfile()d with the current directory set to +# its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import os +import sys +extensions = [ + 'openstackdocstheme', + 'os_api_ref', +] +html_theme = 'starlingxdocs' +html_theme_options = { + "sidebar_dropdown": "api_ref", + "sidebar_mode": "toc", +} +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) +# The suffix of source filenames. +source_suffix = '.rst' +# The master toctree document. +master_doc = 'index' +# General information about the project. +openstackdocs_repo_name = 'openstack/ptp-notification-armada-app' +openstackdocs_auto_name = False +project = u'PTP Status Notifications' +openstackdocs_bug_project = 'starlingx' +openstackdocs_bug_tag = 'openstack/ptp-notification-armada-app' +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = False +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'native' +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', 'stx-ptpnotifications.tex', u'stx-ptpnotifications API Documentation', + u'StarlingX', 'manual'), +] diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 0000000..01f9d83 --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,14 @@ +=========================================== +API Definition for PTP Status Notifications +=========================================== +API Reference for integrating StarlingX with an application that needs to receive PTP status notifications. + +Search PTP Notifications API content using the :ref:`search page `. +-------------- +API definition +-------------- + +.. toctree:: + :maxdepth: 2 + + api_definition_v1_ptp_notifications