NorthStar REST API Notifications
This feature allows third-party applications to receive NorthStar Controller event notifications by subscribing to the NorthStar REST API push notification service. The notifications are pushed by way of the socket.io interface. The following event types are included:
Node (nodeEvent)
Link (linkEvent)
LSP (lspEvent)
P2MP (p2mpEvent)
Facility (facilityEvent)
HA (haEvent)
Table 1 lists the schema for each of these event notification types.
Event Type |
Schema |
Description |
|---|---|---|
nodeEvent |
topology_v2.json#/definitions/nodeNotification |
Node event notification. |
linkEvent |
topology_v2.json#/definitions/linkNotification |
Link event notification. |
lspEvent |
topology_v2.json#/definitions/lspNotification |
LSP event notification. |
p2mpEvent |
topology_v2.json#/definitions/p2mpGroupNotification |
P2MP group event notification. The LSPs in the update are reduced to their lspIndex values to reduce the size of the event. |
facilityEvent |
topology_v2.json#/definitions/facilityNotification |
Facility/SRLG event notification. |
haEvent |
topology_v2.json#/definitions/haHostNotification |
Node state event notification. Only update (no add or remove) events are supported. The notification does not include the list of processes and only contains operational information. |
healthEvent |
topology_v2.json#/definitions/ healthThresholdNotification |
Node health event notification. Only update (no add or remove) events are supported. The notifications include utilization of CPU, disk, memory that exceed certain threshold, and processes status. |
Examples
The following examples are written in Python. Lines preceded by # are comments.
To ensure secure access, a third party application must be authenticated before it can receive NorthStar event notifications. Use the NorthStar OAuth2 authentication API to obtain a token for authentication purposes. The token allows subscription to the socket.io channel. The following example shows connecting to NorthStar and requesting a token.
#!/usr/bin/env python
import requests,json,sys
serverURL = 'https://northstar.example.net'
username = 'user'
password = 'password'
# use NorhtStar OAuth2 authentication API to get a token
payload = {'grant_type': 'password','username': username,'password': password}
r = requests.post(serverURL + ':8443/oauth2/token',data=payload,verify=False,auth=(username, password)) data =r.json()
if "token_type" not in data or "access_token" not in data:
print "Error: Invalid credentials"
sys.exit(1)
# The following header needs to be passed on all subsequent request to REST or Notifications
auth_headers= {'Authorization': "{token_type} {access_token}".format(**data)}
The following example retrieves the NorthStar topology nodes and links.
#!/usr/bin/env python import requests,json,sys serverURL = 'https://northstar.example.net' # auth_headers : see Authentication Token retrieval data = requests.get(serverURL + ':8443/NorthStar/API/v2/tenant/1/topology/1/',verify=False,headers=auth_headers) topology=data.json()
The following example subscribes to the NorthStar REST API push notification service.
#!/usr/bin/env python
from socketIO_client import SocketIO, BaseNamespace
serverURL = 'https://northstar.example.net'
class NSNotificationNamespace(BaseNamespace):
def on_connect(self):
print('Connected to %s:8443/restNotifications-v2'%serverURL)
def on_event(key,name,data):
print "NorthStar Event: %r,data:%r"%(name,json.dumps(data))
# auth_headers : see Authentication Token retrieval
socketIO = SocketIO(serverURL, 8443,verify=False,headers= auth_headers)
ns = socketIO.define(NSNotificationNamespace, '/restNotifications-v2')
socketIO.wait()