HTTP API

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

Specialized Sending Endpoints

In addition to the standard /send endpoint, there are specialized variants for specific use cases:

Send and Close

GET /sendAndClose/:channel/:data

This endpoint sends the data to the specified channel and then attempts to close the browser tab or window. This is particularly useful for physical-digital triggers, such as scanning a QR code to trigger an event, where the user doesn’t need to stay on the confirmation page.

Track (with Metadata)

GET /track/:channel/:data

The track endpoint works similarly to send, but it automatically appends browser metadata to the OOCSI message, including User-Agent, Referer, and Origin. This is useful for analytics or when you need to know more about the client environment that triggered the message.

Use example: Using QR codes with OOCSI

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.

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 Messages via HTTP (SSE)

The HTTP API supports real-time message subscription using Server-Sent Events (SSE). This allows a client (like a web browser or a script) to listen for messages on a specific channel without needing a full WebSocket connection.

To subscribe to a channel, send a GET request to:

GET /subscribe/<channel>

Example (JavaScript):

const eventSource = new EventSource("/subscribe/myChannel");
eventSource.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log("Received:", message);
};

Example (curl):

curl -N https://oocsi.smart.tue.nl/subscribe/myChannel

HTTP Service Bridge (Call-Response)

OOCSI supports a synchronous call-response pattern via HTTP, allowing you to treat OOCSI clients as web services. You can send a request to a specific “service” (channel) and wait for a response.

Making a Service Call

You can trigger a service call via GET or POST:

GET Request:

GET /:service/:call/:data

• :service: The channel name of the service provider.
• :call: The specific command or operation.
• :data: (Optional) Additional data string.

POST Request:

POST /:service/:call

• The body of the POST request serves as the data payload.

Service Responses

The server waits for the OOCSI client to process the request and send a response. The HTTP response format depends on the keys present in the OOCSI response message:

• HTML: If the response contains an html key, the content is returned with Content-Type: text/html.
• JSON: If the response contains a json key, the content is returned as text/json.
• CSV: If the response contains a csv key, the content is returned as text/csv.
• Text: If the response contains a text key, it is returned as text/plain.
• Default: Returns an empty 200 OK if no specific format key is found.