Using REST APIs for PTP Notifications

This section describes the REST APIs by which a hosted DU application can register to receive PTP status notification.

The DU application interfaces with a sidecar residing in the same pod to receive PTP status notifications. The address of the sidecar is the localhost of the pod, and the port of the sidecar is exposed to the DU application by a downward API as environmental variable PTP_SIDECAR_PORT. The sidecar exposes REST API for the DU application to interface. The base URL of the sidecar REST API is http://127.0.0.1:{PTP_SIDECAR_PORT}/ocloudNotifications.

For more information, see the O-RAN specification from ORAN alliance: O-RAN.WG6.O-Cloud Notification API-v03.00.

Get supported versions of PTP notification APIs

Method: GET /api_versions

This method returns a list of all supported versions of PTP notifications APIs. The DU application can query this method and choose the version that is supported by the sidecar.

URL: http://127.0.0.1:{PTP_SIDECAR_PORT}/ocloudNotifications/api_versions

Response body [format : JSON]:


Fields	Type	Values
SubscriptionVersion	list(string)	Example: ["v1", "v2", "v3"]

Example:


Request	Response
http://127.0.0.1/:8080/ocloudNotifications/api_versions	{ "SubscriptionVersion": ["v1"] }

Register for PTP notifications

Method: POST /v1/subscriptions

This method registers the DU application with the sidecar. This method generates a unique identifier (SubscriptionId) for each resource name (ResourceName).

URL: http://127.0.0.1:{PTP_SIDECAR_PORT}/ocloudNotifications/v1/subscriptions

Request body [format : JSON] (*required)

*n (Example: nic1 or nic2)

Note: Depending on the actual configuration, nic1 or both nic1 and nic2 need to be used in the resource address for subscription and query. If the system has only single NIC, use 'nic1'. If system has dual NICs, use nic1 for GNSS-capable NIC and nic2 for the second NIC.

Fields	Type	Values
ResourceAddress	String	Example: "node-1/sync" Available : [ "/./{node-name}/sync/sync-status/sync-state", "/./{node-name}/nic{n}/sync/ptp-status/lock-state", “/./{node-name}/nic{n}/sync/ptp-status/clock-class", “/./{node-name}/sync/sync-status/os-clock-sync-state", “/./{node-name}/sync/gnss-status/gnss-sync-status"]
EndpointUri	String	Example: "http://127.0.0.1:9090/status/ptp"

Fields

Type

Values

ResourceAddress

String

Example: "node-1/sync"
Available : [  "/./{node-name}/sync/sync-status/sync-state",
"/./{node-name}/nic{*n}/sync/ptp-status/lock-state",
“/./{node-name}/nic{*n}/sync/ptp-status/clock-class", 
“/./{node-name}/sync/sync-status/os-clock-sync-state",
“/./{node-name}/sync/gnss-status/gnss-sync-status"]

EndpointUri

String

Example: "http://127.0.0.1:9090/status/ptp"

Response body [format : JSON]


Fields	Type	Values
SubscriptionId	string [format : UUID]	Example: "cebb1ece-bf22-4de9-9424-8307f76bf01d"
UriLocation	string	Example: "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d"
ResourceAddress	string	Example: "node-1/sync" Available : [ "/./{node-name}/sync/sync-status/sync-state", "/./{node-name}/nic{n}/sync/ptp-status/lock-state", “/./{node-name}/nic{n}/sync/ptp-status/clock-class", “/./{node-name}/sync/sync-status/os-clock-sync-state", “/./{node-name}/sync/gnss-status/gnss-sync-status"]
EndpointUri	string	Example: "http://127.0.0.1:9090/status/ptp"

Response codes: Success 201, Bad Request 400, Not Found 404, Already Exists 409, Server Error 500

Examples:

Request	Response
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions { "ResourceAddress" : "node-1/sync", "EndpointUri" : "http://127.0.0.1:9090/ptp/status" }	{ "SubscriptionId": "cebb1ece-bf22-4de9-9424-8307f76bf01d", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d", "ResourceAddress": "node-1/sync", "EndpointUri": "http://127.0.0.1:9090/ptp/status" }

Request

Response

http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions
{
"ResourceAddress" : "node-1/sync",
"EndpointUri" : "http://127.0.0.1:9090/ptp/status"
}

{
	"SubscriptionId": "cebb1ece-bf22-4de9-9424-8307f76bf01d",
	"UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d",
	"ResourceAddress": "node-1/sync",
	"EndpointUri": "http://127.0.0.1:9090/ptp/status"
}

Manage PTP notifications

Method: GET /v1/subscriptions

This method retrieves the list of registration (subscription) information from sidecar.

URL: http://127.0.0.1/:{PTP_SIDECAR_PORT}/ocloudNotifications/v1/subscriptions

Response body [format : JSON]:

Each subscription has the following format.


Fields	Type	Values
SubscriptionId	string [format : UUID]	Example: "cebb1ece-bf22-4de9-9424-8307f76bf01d"
UriLocation	string	Example: "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d"
ResourceAddress	string	Example: "node-1/sync" Available : [ "/./{node-name}/sync/sync-status/sync-state", "/./{node-name}/nic{n}/sync/ptp-status/lock-state", “/./{node-name}/nic{n}/sync/ptp-status/clock-class", “/./{node-name}/sync/sync-status/os-clock-sync-state", “/./{node-name}/sync/gnss-status/gnss-sync-status"]
EndpointUri	string	Exampl: "http://127.0.0.1:9090/status/ptp"

Examples:

Request	Response
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions	[ { "SubscriptionId": "8172e71b-f4b4-4f79-9569-b210f5005cda", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/8172e71b-f4b4-4f79-9569-b210f5005cda", "ResourceAddress": "cell-site-1/worker-node-2/sync", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "6bf100e9-b346-48c4-9c5d-78cc69050e99", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/6bf100e9-b346-48c4-9c5d-78cc69050e99", "ResourceAddress": "cell-site-1/worker-node-2/sync/sync-status/sync-state", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "247fafdb-b0b5-471a-b44e-788f61bef71e", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/247fafdb-b0b5-471a-b44e-788f61bef71e", "ResourceAddress": "cell-site-1/worker-node-2/sync/ptp-status/lock-state", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480", "ResourceAddress": "cell-site-1/worker-node-3/sync/ptp-status/lock-state", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480", "ResourceAddress": "cell-site-1/worker-node-3/sync/ptp-status/ptp-clock-class", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480", "ResourceAddress": "cell-site-1/worker-node-3/sync/sync-status/os-clock-sync-state", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" }, { "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480", "ResourceAddress": "cell-site-1/worker-node-3/sync/gnss-status/gnss-sync-status", "EndpointUri": "http://127.0.0.1:9090/ptp/status2" } ]

Request

Response

http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions

[
   {
      "SubscriptionId": "8172e71b-f4b4-4f79-9569-b210f5005cda",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/8172e71b-f4b4-4f79-9569-b210f5005cda",
      "ResourceAddress": "cell-site-1/worker-node-2/sync",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
   },
   {
      "SubscriptionId": "6bf100e9-b346-48c4-9c5d-78cc69050e99",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/6bf100e9-b346-48c4-9c5d-78cc69050e99",
      "ResourceAddress": "cell-site-1/worker-node-2/sync/sync-status/sync-state",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
   },
   {
     "SubscriptionId": "247fafdb-b0b5-471a-b44e-788f61bef71e",
     "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/247fafdb-b0b5-471a-b44e-788f61bef71e",
      "ResourceAddress": "cell-site-1/worker-node-2/sync/ptp-status/lock-state",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
   },
   {
      "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480",
      "ResourceAddress": "cell-site-1/worker-node-3/sync/ptp-status/lock-state",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
    },
   {
      "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480",
      "ResourceAddress": "cell-site-1/worker-node-3/sync/ptp-status/ptp-clock-class",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
    },

   {
      "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480",
      "ResourceAddress": "cell-site-1/worker-node-3/sync/sync-status/os-clock-sync-state",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
    },

   {
      "SubscriptionId": "3e217afb-85da-4037-a7a9-f59fccf81480",
      "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/3e217afb-85da-4037-a7a9-f59fccf81480",
      "ResourceAddress": "cell-site-1/worker-node-3/sync/gnss-status/gnss-sync-status",
      "EndpointUri": "http://127.0.0.1:9090/ptp/status2"
    }

]

Method: GET /v1/subscriptions/{SubscriptionId}

This method fetches registration information from sidecar based on the registration identifier (SubscriptionId) provided in the URL.

URL: http://127.0.0.1/:{PTP_SIDECAR_PORT}/ocloudNotifications/v1/subscriptions/{SubscriptionId}


Fields	Type	Values
{SubscriptionId}	string [format : UUID]	Example: "cebb1ece-bf22-4de9-9424-8307f76bf01d"

Response body [format : JSON]:


Fields	Type	Values
SubscriptionId	string [format : UUID]	Example: "cebb1ece-bf22-4de9-9424-8307f76bf01d"
UriLocation	string	Example: "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d"
ResourceAddress	string	Example: "node-1/sync" Available : [ "/./{node-name}/sync/sync-status/sync-state", "/./{node-name}/nic{n}/sync/ptp-status/lock-state", “/./{node-name}/nic{n}/sync/ptp-status/clock-class", “/./{node-name}/sync/sync-status/os-clock-sync-state", “/./{node-name}/sync/gnss-status/gnss-sync-status"]
EndpointUri	string	Example: "http://127.0.0.1:9090/status/ptp"

Response codes: Success 200, Bad Request 400, Not Found 404, Server Error 500

Examples:

Request	Response
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d	{ "SubscriptionId": "cebb1ece-bf22-4de9-9424-8307f76bf01d", "UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d", "ResourceAddress" : "node-1/sync", "EndpointUri": "http://127.0.0.1:9090/ptp/status" }

Request

Response

http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d

{
	"SubscriptionId": "cebb1ece-bf22-4de9-9424-8307f76bf01d",
	"UriLocation": "http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d",
	"ResourceAddress" : "node-1/sync",
	"EndpointUri": "http://127.0.0.1:9090/ptp/status"
}

Method: DELETE /v1/subscriptions/{SubscriptionId}

This method deletes the registration from the sidecar based on the registration identifier (SubscriptionId) provided in the URL. After this method is run successfully, the DU application will not receive the notifications corresponding to the registration identifier.

URL: http://127.0.0.1/:{PTP_SIDECAR_PORT}/ocloudNotifications/v1/subscriptions/{SubscriptionId}


Fields	Type	Values
{SubscriptionId}	string [format : UUID]	Example: "cebb1ece-bf22-4de9-9424-8307f76bf01d"

Response body: No response

Response codes: Success 204, Not Found 404, Server Error 500

Examples:


Request
http://127.0.0.1:8080/ocloudNotifications/v1/subscriptions/cebb1ece-bf22-4de9-9424-8307f76bf01d

Query PTP status

Method: GET /v1/{Resource}/currentstate

This method fetches the current status of the PTP status. DU application can actively use this method to get the current status of PTP instead of waiting on the sidecar to send the notifications.

URL: http://127.0.0.1/:{PTP_SIDECAR_PORT}/ocloudNotifications/v1/{Resource}/currentstate


Fields	Type	Values
{Resource}	string	Available : ["/sync/sync-status/sync-state", "/sync/ptp-status/lock-state", “/sync/ptp-status/ptp-clock-class", “/sync/sync-status/os-clock-sync-state", "/sync/gnss-status/gnss-sync-status"]

Response body [format: JSON]:


Fields	Type	Values
id	string [format : UUID]	Example: "97685863-8755-48cf-9c7d-a33a6036edef"
specversion	string	Available : "1.0"
source	string	Available : ["/sync/sync-status/sync-state", "/sync/ptp-status/lock-state", “/sync/ptp-status/ptp-clock-class", “/sync/sync-status/os-clock-sync-state", "/sync/gnss-status/gnss-sync-status"]
type	string	Available : ["event.sync.sync-status.synchronization-state-change", "event.sync.ptp-status.lock-state-change", “event.sync.ptp-status.ptp-clock-class", “event.sync."sync-status.os-clock-sync-state", “event.sync.gnss-status.gnss-sync-status"]
time	string [Format : date-time]	Example: "2022-01-27T01:24:56.188Z"
version	string	Available : "1.0"
data_type	string	Available : "notification"
resource_address	string	Example: "node-1/sync/sync-status/sync-state" Available : ["{node-name}/sync/sync-status/sync-state", "{node-name}/sync/ptp-status/lock-state", “{node-name}/sync/ptp-status/ptp-clock-class", “{node-name}/sync/sync-status/os-clock-sync-state", “{node-name}/sync/gnss-status/gnss-sync-status"]
value_type	string	Available : "enumeration"
value	string	Synchronization State - Available : ["LOCKED", "HOLDOVER", "FREERUN"] Default: "FREERUN" GNSS-Sync-State - Available : ["SYNCHRONIZED", "ANTENNA-DISCONNECTED", "FAILURE-NOFIX"]

Response codes: Success 200, Not Found 404, Server Error 500

Examples:

Request	Response
http://127.0.0.1/:8080/ocloudNotifications/v1/sync/sync-status/sync-state/currentstate	{ "id": "97685863-8755-48cf-9c7d-a33a6036edef", "specversion": "1.0", "source": "/sync/sync-status/sync-state", "type": "event.sync.sync-status.synchronization-state-change", "time": "2021-03-05T20:59:00.999999999Z", "data": { "version": "1.0", "values": [{ "data_type": "notification", "resource_address": "/node-1/sync/sync-status/sync-state", "value_type": "enumeration", "value": "HOLDOVER" }] } }

Request

Response

http://127.0.0.1/:8080/ocloudNotifications/v1/sync/sync-status/sync-state/currentstate

{
    "id": "97685863-8755-48cf-9c7d-a33a6036edef",
    "specversion": "1.0",
    "source": "/sync/sync-status/sync-state",
    "type": "event.sync.sync-status.synchronization-state-change",
    "time": "2021-03-05T20:59:00.999999999Z",
    "data": {
        "version": "1.0",
        "values": [{
                "data_type": "notification",
                "resource_address": "/node-1/sync/sync-status/sync-state",
                "value_type": "enumeration",
                "value": "HOLDOVER"
        }]
    }
}

Notify PTP status

Method: POST {CallbackUri}

The sidecar uses this method to post notifications to the DU application. The CallbackUri is provided by the DU application during registration.

Callback URI (example): http://127.0.0.1:9090/status/ptp

Request body [format : JSON] (*required):


Fields	Type	Values
id	string [format : UUID]	Example: "97685863-8755-48cf-9c7d-a33a6036edef"
specversion	string	Available : "1.0"
source	string	Available : ["/sync/sync-status/sync-state", "/sync/ptp-status/lock-state", “/sync/ptp-status/ptp-clock-class", “/sync/sync-status/os-clock-sync-state", "/sync/gnss-status/gnss-sync-status"]
type	string	Available : ["event.sync.sync-status.synchronization-state-change", "event.sync.ptp-status.lock-state-change", “event.sync.ptp-status.ptp-clock-class", “event.sync."sync-status.os-clock-sync-state", “event.sync.gnss-status.gnss-sync-status"]
time	string [Format : date-time]	Example: "2022-01-27T01:24:56.188Z"
version	string	Available : "1.0"
data_type	string	Available : "notification"
resource_address	string	Example: "node-1/sync/sync-status/sync-state" Available : [ "/./{node-name}/sync/sync-status/sync-state", "/./{node-name}/nic{n}/sync/ptp-status/lock-state", “/./{node-name}/nic{n}/sync/ptp-status/clock-class", “/./{node-name}/sync/sync-status/os-clock-sync-state", “/./{node-name}/sync/gnss-status/gnss-sync-status"]
value_type	string	Available : "enumeration"
value	string	Synchronization State - Available : ["LOCKED", "HOLDOVER", "FREERUN"] Default: "FREERUN" GNSS-Sync-State - Available : ["SYNCHRONIZED", "ANTENNA-DISCONNECTED", "FAILURE-NOFIX"]

Response codes: Success 204, Bad Request 400, Not Found 404, Timeout 408, Server Error 500.

Examples:

Request
{ "id": "97685863-8755-48cf-9c7d-a33a6036edef", "specversion": "1.0", "source": "/sync/sync-status/sync-state", "type": "event.sync.sync-status.synchronization-state-change", "time": "2021-03-05T20:59:00.999999999Z", "data": { "version": "1.0", "values": [{ "data_type": "notification", "resource_address": "/node-1/sync/sync-status/sync-state", "value_type": "enumeration", "value": "HOLDOVER" }] } }

Request

{
    "id": "97685863-8755-48cf-9c7d-a33a6036edef",
    "specversion": "1.0",
    "source": "/sync/sync-status/sync-state",
    "type": "event.sync.sync-status.synchronization-state-change",
    "time": "2021-03-05T20:59:00.999999999Z",
    "data": {
        "version": "1.0",
        "values": [{
                "data_type": "notification",
                "resource_address": "/node-1/sync/sync-status/sync-state",
                "value_type": "enumeration",
                "value": "HOLDOVER"
        }]
    }
}