Cisco Prime Infrastructure API
Prime Infrastructure API Documentation

NBI Server-Sent Events

Server-Sent Events are asynchronous messages sent by Prime Infrastructure to notify consumers of a set of key events. Prime Infrastructure uses the W3C Server-Sent Events technology to send notification messages to consumers.

Events

Prime Infrastructure sends several types of events. Each event has its own type. You may subscribe to all of them or only those that you want to receive.

Event Description
event An event data message that is sent when an entity is created, updated, or deleted. Contains at least one event. See Response Format section for details.
event: event
data: <?xml version="1.0" ?>
 <streamResponse type="Alarms" responseType="listEvents"
	requestUrl="https://my_server/webacs/api/v4/sse/Alarms" rootUrl="https://my_server/webacs/api/v4/sse">
	 <streamEvent dtoType="alarmsDTO" id="1107124" action="UPDATED" eventTime="2018-11-22T08:40:16.208Z">
		 <alarmsDTO displayName="1107124" id="1107124">
...
		 </alarmsDTO>
	 </streamEvent>
 </streamResponse>
error An event indicating that an error occurred while processing events. Will contain descriptive error message.
event: error
data: <streamError message="Active virtual domain has been removed. The connection will be closed, try to reconnect." />
ping A service event that is sent to check if the client is still alive. Prime Infrastructure sends them every 30 seconds. The event message contain no data and will be ignored by an SSE client.
event: ping
: ping
greeting A service event that is sent immediately after the client has been connected. The event message contain no data and will be ignored by a SSE client.
event: greeting
: Successfully subscribed to Alarms events

Requests

URL Patterns

URL Pattern Request-Type Function
/api/v4/sse GET Get all event types.
/api/v4/sse/{eType} GET Subscribe to events of {eType} entity, for example Alarms.
/api/v4/sse/{eType}/{aType} GET Subscribe to events of {eType} entity of {aType} event type, for example Alarms/CREATED.

Query Parameters

Query Parameter Meaning
.json When present, indicates that the response should be returned in json format. Can be used when your SSE client does not support sending additional HTTP headers.
.xml When present, indicates that the response should be returned in xml format. This is the default behavior in the absence of the .json parameter. Can be used when your SSE client does not support sending additional HTTP headers.
_docs Displays the documentation page.
_ctx.domain Sets the active domain to be that named in the query parameter value - this is, by default, "sticky" in the sense that once set, the active-domain remains set. The "stickiness" is not RESTful, and so it can be switched off in configuration.

HTTP Headers

HTTP Header Value Meaning
Accept text/xml or application/json May be used to control whether the event returned is formatted as XML or JSON.
Accept-Language For example: en-US Specifies the language to be used in the response. This may affect error messages that may be returned.
Accept-Encoding gzip Specifies that compressed data may be returned to the client.
Content-Encoding gzip Specifies that data supplied by the client with a request is compressed.

Response Format

An SSE event stream is delivered as a streaming HTTP response. The server responds with a custom "text/event-stream" content-type, and then streams the UTF-8 encoded event data. Event data format can be either xml or json depending on the requested format.

Entity event data is returned in an 'envelope' that has this structure:

<?xml version="1.0" encoding="utf-8"?>
 <streamResponse  type="Alarms"  rootUrl="https://my_server/webacs/api/v4/sse"
	 requestUrl="https://my_server/webacs/api/v4/sse/Alarms"
	 responseType="listEvents">
...
 </streamResponse>

The structure consists of:

  • /streamResponse

    The top-level element in the response document, with the following attributes:

    • /streamResponse/@responseType - The response-type indicates the type of request made. It can assume one of these values:
      • listEntityTypes: The type of the entity events requested (http://.../sse).
      • listEvents - entity events requested - http://.../sse/<event-type>
    • /streamResponse/@rootUrl - The full URL that was sent in the request.
    • /streamResponse/@requestUrl - The URL that identifies the root of all requests to the REST interface as currently deployed.
    • /streamResponse/@type Optional - The type of entity event requested, where a request for a specific entity event is requested.

Depending on the value of the /streamResponse/@responseType attribute the elements that form the contents of the <streamResponse> will be as follows:

  • (@responseType="listEntityTypes")

    /streamResponse/entityType

  • (@responseType="listEvents")

    /streamResponse/streamEvent* - Each element contains the structured data that describes an entity event.

Error Format

Errors that occur while establishing SSE connection are reported in a canonical error document in the same format as used for /op and /data requests. Errors that occur after the SSE connection is established are reported as a SSE messages with error data type.

Depending on the severity of the error the connection may be persisted or closed. We explicitly close connections in following cases:

  • The active virtual domain has been removed
  • The active user has been modified, deleted, or locked.

You will get an error message indicating that an error occurred before the connection is closed.

event: error
data: <streamError message="Active virtual domain has been removed. The connection will be closed, try to reconnect."/>

The document structure is as follows:

  • /streamError - The envelope that contains the error data.
  • /streamError/message - A user-friendly message carried by an exception.