API Documentatie

Pusher-compatibele REST API

📑 Inhoud

Introductie
Authenticatie
Endpoints
Trigger Event
Batch Events
Get Channels
Get Channel Info
Get Channel Users
Terminate User
Migratie van Pusher
Voorbeelden

📘 Introductie

Skubber Push Server ondersteunt de Pusher Channels REST API endpoints, waardoor je een drop-in replacement hebt voor Pusher. Gebruik dezelfde API structuur maar met eenvoudigere authenticatie en zonder dure abonnementen.

✨ Voordelen:

Dezelfde API endpoints als Pusher
Eenvoudigere authenticatie (geen HMAC signatures)
Tot 90% goedkoper dan Pusher
Onbeperkt aantal berichten en connecties (Premium)
Volledige controle over je data

🔐 Authenticatie

REST API Endpoints

Voor REST API endpoints gebruik je HTTP headers met je API Key en Secret:

X-Api-Key: mps_htU8zSQ4LtzyjzIhLV15mPSIk3zSJSaw
X-Api-Secret: qSgM0erFzC3JpB2fsR966MhsbpbTxqfoO1prBSB1VtnbbAnf

Of als query parameters:

?apiKey=your-api-key&apiSecret=your-api-secret

SignalR Connecties (Browser/Client)

⚠️ BELANGRIJK: Stuur NOOIT je API Secret naar de browser! Gebruik in plaats daarvan een JWT token:

// Stap 1: Haal JWT token op (server-side of via veilige endpoint)
const response = await fetch('https://sps.skubber.com:5187/api/auth/signalr-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        apiKey: 'mps_htU8zSQ4LtzyjzIhLV15mPSIk3zSJSaw',
        apiSecret: 'qSgM0erFzC3JpB2fsR966MhsbpbTxqfoO1prBSB1VtnbbAnf'
    })
});
const { token } = await response.json();

// Stap 2: Gebruik alleen de token voor SignalR (veilig!)
const connection = new signalR.HubConnectionBuilder()
    .withUrl(`https://sps.skubber.com:5187/push?userId=user123&access_token=${token}`)
    .build();

💡 Waarom JWT tokens?
JWT tokens zijn tijdelijk (vervallen na 1 uur) en bevatten geen geheimen. Als iemand je token steelt, heeft deze slechts beperkte tijd toegang en kan deze geen nieuwe tokens genereren. Je API Secret blijft veilig op de server!

🚀 Beschikbare Endpoints

POST /apps/{appId}/events

Trigger Event

Stuurt een event naar één of meerdere channels.

Parameter / Type / Beschrijving

Parameter	Type	Beschrijving
`name` Verplicht	string	Naam van het event
`data` Verplicht	string	Event data als JSON string (max 10KB)
`channel` Optioneel	string	Enkele channel naam
`channels` Optioneel	array	Array van channel namen (max 100)
`socket_id` Optioneel	string	Sluit specifieke connectie uit
`info` Optioneel	string	Comma-separated lijst: user_count, subscription_count

Voorbeeld Request:

{
  "name": "my-event",
  "data": "{\"message\":\"Hello World\"}",
  "channels": ["test-channel", "another-channel"]
}

Response:

{}

Of met info:

{
  "channels": {
    "presence-room": {
      "user_count": 42,
      "subscription_count": 51
    }
  }
}

POST /apps/{appId}/batch_events

Batch Events

Stuurt meerdere events tegelijk (max 10 per batch).

Voorbeeld Request:

{
  "batch": [
    { "name": "event1", "channel": "channel1", "data": "{\"key\":\"value\"}" },
    { "name": "event2", "channel": "channel2", "data": "{\"other\":\"data\"}" }
  ]
}

Response:

{ "batch": [{}, {}] }

GET /apps/{appId}/channels

Get Channels

Haal lijst van actieve channels op.

Parameter	Beschrijving
`filter_by_prefix`	Filter channels op prefix (bijv. "presence-")
`info`	Comma-separated lijst van attributes

{
  "channels": {
    "presence-room1": { "user_count": 42 },
    "my-channel": { "subscription_count": 10 }
  }
}

GET /apps/{appId}/channels/{channelName}

Get Channel Info

Haal info op over een specifieke channel.

{ "occupied": true, "user_count": 42, "subscription_count": 51 }

GET /apps/{appId}/channels/{channelName}/users

Get Channel Users

Haal lijst van users in een presence channel op.

Note: Alleen beschikbaar voor presence channels (naam begint met "presence-")

{ "users": [ { "id": "user1" }, { "id": "user2" } ] }

POST /apps/{appId}/users/{userId}/terminate_connections

Terminate User Connections

Beëindigt alle connecties van een specifieke user.

Note: Vereist admin scope in API key

{}

🔄 Migratie van Pusher

Om van Pusher naar Skubber te migreren:

1. Wijzig de base URL

// From:
https://api-{cluster}.pusher.com

// To:
https://sps.skubber.com:5187

2. Pas authenticatie aan

// Pusher (complex):
auth: { params: { auth_key: '...', auth_signature: '...', auth_timestamp: '...', body_md5: '...' } }

// Skubber (eenvoudig):
headers: { 'X-Api-Key': 'your-api-key', 'X-Api-Secret': 'your-api-secret' }

3. Gebruik dezelfde endpoints

Alle endpoint paden blijven hetzelfde!

💻 Code Voorbeelden

cURL

curl -X POST "https://sps.skubber.com:5187/apps/myapp/events" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -H "X-Api-Secret: your-api-secret" \
  -d '{ "name": "my-event", "channels": ["test-channel"], "data": "{\"message\":\"Hello World\"}" }'

JavaScript / Node.js

const response = await fetch('https://sps.skubber.com:5187/apps/myapp/events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'your-api-key', 'X-Api-Secret': 'your-api-secret' },
  body: JSON.stringify({ name: 'my-event', channels: ['test-channel'], data: JSON.stringify({ message: 'Hello World' }) })
});

Python

import requests, json
requests.post('https://sps.skubber.com:5187/apps/myapp/events',
    headers={ 'Content-Type': 'application/json', 'X-Api-Key': 'your-api-key', 'X-Api-Secret': 'your-api-secret' },
    json={ 'name': 'my-event', 'channels': ['test-channel'], 'data': json.dumps({'message': 'Hello World'}) }
)

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "your-api-key");
client.DefaultRequestHeaders.Add("X-Api-Secret", "your-api-secret");
var response = await client.PostAsJsonAsync("https://sps.skubber.com:5187/apps/myapp/events", new {
    name = "my-event", channels = new[] { "test-channel" },
    data = JsonSerializer.Serialize(new { message = "Hello World" })
});

🎯 Limitaties

Max 10KB per event (zoals Pusher)
Max 100 channels per event (zoals Pusher)
Max 10 events per batch (zoals Pusher)

✅ Klaar om te beginnen?
Vraag je API Key aan en begin binnen 5 minuten met pushen!