HTTP API

Sending data (send)

If you just want to send OOCSI messages to a channel or client, for instance, to trigger something or make a selection, you can do this with the HTTP API. Let’s say your OOCSI server is available at https://demo.oocsi.net, then you can send an OOCSI message with a simple parameter “testingThis” to the channel test-http-api with:

https://demo.oocsi.net/send/test-http-api/testingThis

The first part is the server URL, then you add /send/ and then the channel test-http-api, then / and finally, you append the parameter testingThis.

If you would like to send more structured data, you need to send a POST request to the URL:

https://demo.oocsi.net/send/test-http-api

The POST request needs to have a JSON formatted body or url-encoded form content.

On the command line, this would look like this:

curl --header "Content-Type: application/json" \
  	--request POST \
  	--data '{"color":"blue","number":12,"light":true}' \
  	https://demo.oocsi.net/send/test-http-api

Now that you know how to create URLs that send data to OOCSI when they are opened in a browser, you can make QR codes of these URLs and let people scan them and easily onboard them onto the OOCSI network.

Identifying users with cookies

The HTTP API uses HTML cookies to remember browsers. So, when a browser (on a laptop or mobile phone) opens one of the HTTP API URLs that you have created, OOCSI will also set a cookie on this browser. The next time (within 24 hours) that the browser opens the same or another HTTP API URL, the cookie will be recognized and you will receive the same user id. This way, you can track different users in an application.

Note, that these cookies do not store personal information and they expire after 24 hours. Nevertheless, you might need to inform your users or participants about this.

Receiving data (subscribe)

It is also possible to subscribe to an OOCSI channel via the HTTP API to receive data. Technically, this is realized with server-sent events (SSE). When you subscribe to a channel, you open a long-lasting connection that streams data back to your client, which you can then process further.

A simple example on the command line is

curl -sN https://demo.oocsi.net/subscribe/testchannel

which results in continuous output on the command line. You can filter the output, e.g., by extracting JSON properties like so:

curl -sN https://demo.oocsi.net/subscribe/testchannel | sed -u 's/^data: //' | jq '.position'

What we do here, initiate the stream, pipe the received stream chunks to another command line util sed which replaces the leading “data: “ string, then pipe the result to the second command line util jq which can do JSON operations. Here, we just extract the “position” property that is included in every message from “testchannel”.