
Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager API Documentation

# NBI Server-Sent Events

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

## Events

Evolved Programmable Network Manager 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" count="3"
    	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. Evolved Programmable Network Manager 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" count="3">
    ...
    </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/@count - Number of entities in the envelope.
  - /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.