The subscription API provides real-time subscription service for external client applications.

Subscribe

Provides a subscription service to the transaction collection of a storage unit. The service will automatically push new transaction records to the subscriber clients. The subscription service uses Server-Sent Events.

Reconnection: If the connection is lost by the client, when reconnecting it will send a last-event-id header with the last transaction id that was received by the client. The subscription service will resume from the last-event-id.

Request

The subscribe GET request receives the storage unit name to subscribe to. Optionally a start transaction id can be provided, the server will send transactions starting on this transaction id. If the start id is not provided, all transactions are sent.

Java example

Client client = ClientBuilder.newBuilder().register(SseFeature.class).build();
WebTarget target = client.target(new URI("http://localhost:3000/subscription/subscribe/<storage-unit-name>"));
EventSource eventSource = EventSource.target(target).reconnectingEvery(2, TimeUnit.SECONDS).build();
EventListener listener = new EventListener(){
  public void onEvent(InboundEvent inboundEvent) {
    System.out.println(inboundEvent.getId() + "; "
    + inboundEvent.readData(String.class).length());
  }
};    
eventSource.register(listener);
eventSource.open();
...
eventSource.close();

Javascript example

var source = new EventSource('http://localhost:3000/subscription/subscriptionEvent/<storage-unit-name>');
source.onmessage = function (e) {
    console.log(e.lastEventId + ':' + e.data.length);
};

Response

The response is of text/event-stream Content-type and remains open until the client decides to unsubscribe. Each transaction record is returned as a single event with the transaction id as the event id and the transaction JSON as the data. Each new event message is separated by two new lines (\n\n).

id: 5644f2d497cc11144081d111\n
data: {"_id" : 5644f2d497cc11144081d111, "metadata" : {...}, "scope" : "ocr", "recordId" : "E0F57D337D5021236E353C7AB305F147", "timestamp" : 2015-11-12T20:13:08.243Z, "type" : "ADD", "__v" : 0}\n\n