Exoware API Documentation

v0.0.2

The canonical interface for all Exoware Components. Try it in the Exoware Sandbox.

Authentication

Authentication requirements are determined by the Exoware Component deployer. When authentication is enabled, you can provide credentials using either method:

Error Handling

The API uses standard HTTP status codes:

> Store Operations

Persist and retrieve artifacts.

GET /store/{key} Get a value
>

Summary: Get a value

Retrieves a value from the store by its key.

Parameters:

key (path) required
The key for the store operation.
token (query) optional
Authentication token, can be used as an alternative to the Authorization header.

Responses:

200 OK - Returns the base64-encoded value
401 Unauthorized
404 Not Found
500 Internal Server Error

Example Response (200):

{
    "value": "SGVsbG8gV29ybGQ="
}

Invariants:

Eventual Consistency: A value updated by POST /store/{key} may take up to 60 seconds to be reflected in the GET /store/{key} operation.
Max Key Size: The maximum size of the key is 512 bytes.
POST /store/{key} Set a value
>

Summary: Set a value

Updates a key-value pair in the store (or creates it if it doesn't exist).

Parameters:

key (path) required
The key for the store operation.
token (query) optional
Authentication token, can be used as an alternative to the Authorization header.

Request Body:

Content-Type: application/octet-stream

Binary data to store as the value.

Responses:

200 OK
401 Unauthorized
413 Payload Too Large
429 Too Many Requests
500 Internal Server Error

Invariants:

Rate Limit: This operation can be called at most once per second for each key.
Max Key Size: The maximum size of the key is 512 bytes.
Max Value Size: The maximum size of the value is 20MB (20,971,520 bytes).
GET /store Query for key-value pairs
>

Summary: Query for key-value pairs

Queries for a range of key-value pairs.

Parameters:

token (query) optional
Authentication token, can be used as an alternative to the Authorization header.
start (query) optional
The key to start the query from (inclusive).
end (query) optional
The key to end the query at (exclusive).
limit (query) optional
The maximum number of results to return.

Responses:

200 OK - Returns array of key-value pairs
401 Unauthorized
500 Internal Server Error

Example Response (200):

{
    "results": [
        {
            "key": "user:123",
            "value": "eyJuYW1lIjoiSm9obiJ9"
        },
        {
            "key": "user:124",
            "value": "eyJuYW1lIjoiSmFuZSJ9"
        }
    ]
}

Invariants:

Eventual Consistency: A value updated by POST /store/{key} may take up to 60 seconds to be reflected in the GET /store operation.
Max Key Size: The maximum size of the key is 512 bytes.

> Stream Operations

Broadcast realtime data.

POST /stream/{name} Publish to a stream
>

Summary: Publish to a stream

Publishes a message to a stream.

Parameters:

name (path) required
The name of the stream.
token (query) optional
Authentication token, can be used as an alternative to the Authorization header.

Request Body:

Content-Type: application/octet-stream

Binary data to publish to the stream.

Responses:

200 OK
401 Unauthorized
500 Internal Server Error

Invariants:

Max Name Size: The maximum size of the stream name is 512 bytes.
Max Message Size: The maximum size of the message is 20MB (20,971,520 bytes).
GET /stream/{name} Subscribe to a stream (WebSocket)
>

Summary: Subscribe to a stream

Subscribes to a stream via WebSocket.

Parameters:

name (path) required
The name of the stream.
token (query) optional
Authentication token, can be used as an alternative to the Authorization header.

Responses:

101 Switching Protocols - WebSocket connection established
401 Unauthorized
500 Internal Server Error

WebSocket Usage:

// Without authentication
const ws = new WebSocket('ws://localhost:8080/stream/events');

// With authentication token
const wsAuth = new WebSocket('ws://localhost:8080/stream/events?token=YOUR_TOKEN_HERE');

// Handle messages
ws.onmessage = (event) => {
    console.log('Received:', event.data);
};

Invariants:

Max Name Size: The maximum size of the stream name is 512 bytes.