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 <udi.schwager@windriver.com> Change-Id: I8eed27322433f565c66c1a566ac8bbef0b8903b8
This commit is contained in:
Udi Schwager
parent
1ca32529ad
commit
0a840ffe37
315
api-ref/source/api_ptp_notifications_definition_v1.rst
Normal file
315
api-ref/source/api_ptp_notifications_definition_v1.rst
Normal file
@ -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"
|
||||
}
|
||||
64
api-ref/source/conf.py
Normal file
64
api-ref/source/conf.py
Normal file
@ -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'),
|
||||
]
|
||||
14
api-ref/source/index.rst
Normal file
14
api-ref/source/index.rst
Normal file
@ -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 <search>`.
|
||||
--------------
|
||||
API definition
|
||||
--------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api_definition_v1_ptp_notifications
|
||||
Loading…
Reference in New Issue
Block a user