HTTP API Overview

Sockudo implements an HTTP API compatible with the Pusher Channels HTTP API. This API allows your backend application to interact with the Sockudo server to publish events, query channel information, and manage users.

All requests to the HTTP API must be authenticated.

Base Path

The base path for the HTTP API is typically /apps/{app_id}/, where {app_id} is the unique ID of your application configured in Sockudo.

Example: http://localhost:6001/apps/my-cool-app/

If you have configured a path_prefix in Sockudo (e.g., /sockudo_api), it will prepend this base path: Example: http://localhost:6001/sockudo_api/apps/my-cool-app/

Authentication

All HTTP API requests must be authenticated using a set of query parameters that include your application's auth_key (app key) and a signature generated using your auth_secret (app secret).

The required authentication query parameters are:

• auth_key: Your application key.
• auth_timestamp: A Unix timestamp (seconds since epoch) of when the request was made. Requests with timestamps too far in the past or future might be rejected.
• auth_version: The authentication protocol version (e.g., "1.0").
• auth_signature: An HMAC-SHA256 signature.

Generating the Signature:

The signature is generated by creating a string-to-sign and then hashing it with your app_secret. The string-to-sign typically includes:

1. HTTP Method (UPPERCASE, e.g., POST)
2. Request Path (e.g., /apps/my-app-id/events)
3. Sorted Query Parameters (excluding auth_signature itself, including auth_key, auth_timestamp, auth_version, and any other query parameters, sorted alphabetically by key).
4. If the request has a body (e.g., POST with JSON), the MD5 hash of the request body is often included in the string-to-sign or as a query parameter body_md5.

Example string-to-sign (conceptual, precise format depends on Pusher library used):

POST /apps/YOUR_APP_ID/events auth_key=YOUR_APP_KEY&auth_timestamp=1678886400&auth_version=1.0&body_md5=YOUR_BODY_MD5_HASH&name=my-event&channels[]=my-channel&data={"message":"hello"} Then, signature = hmac_sha256(string_to_sign, YOUR_APP_SECRET).

Using Pusher Server Libraries: It is highly recommended to use official or community-maintained Pusher server libraries for your backend language (PHP, Node.js, Python, Ruby, Java, etc.). These libraries handle the complexities of authentication and request formatting for you.

When configuring these libraries, you'll typically provide:

• app_id
• key (auth_key)
• secret (auth_secret)
• host (your Sockudo server host)
• port (your Sockudo server port)
• scheme (http or https if SSL is enabled)

Common HTTP API Endpoints

The following pages detail the specific HTTP API endpoints supported by Sockudo:

• Trigger Events: Publish a single event to one or more channels.
• Batch Events: Publish multiple events in a single request.
• Channel Information: Get information about channels and their subscribers.
• User Management: Manage user connections (e.g., terminate user sessions).

Request and Response Format

• Requests:
  • Content-Type for POST requests with a body is typically application/json.
• Responses:
  • Successful requests usually return a 200 OK or 202 Accepted status code.
  • The response body is often JSON. For event publishing, an empty JSON object {} is common on success.
  • Errors are indicated by 4xx or 5xx status codes with a JSON body describing the error.
    • 400 Bad Request: Invalid request parameters or body.
    • 401 Unauthorized: Authentication failure (e.g., invalid signature, unknown app key).
    • 403 Forbidden: Authenticated but not authorized for the action (e.g., app disabled, trying to publish to too many channels).
    • 404 Not Found: Resource not found (e.g., querying a non-existent channel or app).
    • 413 Payload Too Large: Request body exceeds configured limits.

Rate Limiting

HTTP API endpoints are subject to rate limiting if configured in Sockudo. Exceeding the rate limit will typically result in a 429 Too Many Requests error. See Rate Limiter Configuration.