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

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 O-RAN specifications from ORAN alliance.

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 a single NIC, use 'nic1'. If the 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"
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"
}

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"
    }

]
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"
}
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"
        }]
    }
}

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"
        }]
    }
}