v8 v7 v6 v5 v4 v3
Edit Page

Examples of the WebSocket API

The following requests upsert a collection defining three change streams:

  • all bound at /messages/_streams/all

  • mine bound at /messages/_streams/mine

Request 
PUT /messages HTTP/1.1
Request body 
{
    "streams" : [
      { "stages" : [
          {
              "_$match": {
                "_$or" : [ { "operationType": "insert" }, { "operationType": "update" } ]
            }
          }
      ],
        "uri" : "all"
      },
      { "stages" : [
          { "_$match" : { "fullDocument::name" : { "_$var" : "n" } } }
        ],
        "uri" : "mine"
      }
    ]
}

Note that the $match stage specifies a condition on the name property using fullDocument::name.

This is because the Change Event looks like:

{
    "fullDocument": {
        "_id": { "$oid": "5e15ff5779ca449eb20fdd09" },
        "message": "hi uji, how are you?",
        "name": "uji",
        "_etag": { "$oid": "5e15ff57a2e5700c3459e801" }
    },
    "documentKey": {
        "_id": { "$oid": "5e15ff5779ca449eb20fdd09" }
    },
    "updateDescription": null,
    "operationType": "insert"
}

Note between the _links collection property the URIs of the change streams (returned with ?rep=SHAL).

Request 
GET /messages?rep=SHAL HTTP/1.1
Response 
{
    "_links": {
        "all": {
            "href": "/messages/_streams/all"
        },
        "mine": {
            "href": "/messages/_streams/mine"
        }
    }
}

Alternatively, we can define a single change stream that either returns all messages or only those sent by a specific name`. This can be achieved through a definition that utilizes optional stages:

{
    "streams" : [
{ "stages" : [
          { "$ifvar": [ "n", { "_$match" : { "fullDocument::name" : { "_$var" : "n" } } } ] }
        ],
        "uri" : "withOptionalStage"
      }
    ]
}

To subscribe to the change streams, we will use websocat, a Command-line client for WebSockets, like netcat (or curl) for ws://

Tip
 You can install websocat following the instructions at https://github.com/vi/websocat#installation or downloading binaries from https://github.com/vi/websocat/releases

Connect to the change streams using the following command, given that the default user admin exists with the default password:

$ websocat --text - autoreconnect:ws://admin:secret@127.0.0.1:8080/messages/_streams/all

To allow connections without authentication, you can define the following permission

POST /acl HTTP/1.1
Request body 
{
    "_id": "unauthenticatedCanConnectToMyWebSocket",
    "predicate": "path-prefix('/messages/_streams/all')",
    "priority": 0,
    "roles": [ "$unauthenticated" ]
}

With this permission in place, you can connect to the WebSocket without authentication:

$ websocat --text - autoreconnect:ws://127.0.0.1:8080/messages/_streams/all

If we now create a new document in the collection messages

POST /messages HTTP/1.1
Request body 
{
    "message": "Hello WebSockets!",
    "name": "uji"
}

We get the following output from websocat:

$ websocat --text - autoreconnect:ws://admin:secret@127.0.0.1:8080/messages/_streams/all
{"fullDocument":{"_id":{"$oid":"62166d53ebdcd56455a1a7ab"},"message":"Hello WebSockets!","name":"uji","_etag":{"$oid":"62166d53ebdcd56455a1a7aa"}},"documentKey":{"_id":{"$oid":"62166d53ebdcd56455a1a7ab"}},"operationType":"insert"}