Updated API and WS pages.
This commit is contained in:
+37
-108
@@ -6,29 +6,26 @@ Player service base URL default for local setups: `http://localhost:3001`
|
||||
|
||||
In Docker or behind a reverse proxy, use the player service address exposed in your deployment instead.
|
||||
|
||||
This document covers the player HTTP surface only. The admin dashboard exposes its own routes for screen commands and onboarding management.
|
||||
The player API is split into public endpoints that are safe to use within the trusted deployment network and secure endpoints that require the shared-secret-backed auth flow.
|
||||
|
||||
Access note: most player endpoints are unauthenticated because they are meant to run inside a trusted deployment network. Anything that mutates state or writes files should be treated as internal-only unless you add your own auth layer in front of it.
|
||||
Access legend:
|
||||
|
||||
When `PULSE_SIGNAGE_SHARED_SECRET` is set, the player pages sign same-origin API fetches with `x-pulse-page-auth`, and the web app signs server-to-player requests with `x-pulse-request-timestamp` plus `x-pulse-request-signature`. Page tokens auto-renew before expiry while the page stays active, and signed server requests are only accepted when their timestamp is fresh. If the secret is unset, those checks stay disabled for compatibility.
|
||||
- 🌐 Public: available within the trusted deployment network.
|
||||
- 🔑 Secure: requires internal auth or a shared-secret-backed request.
|
||||
|
||||
## Endpoints
|
||||
## 🌐 Public Endpoints
|
||||
|
||||
### `GET /`
|
||||
Returns the player onboarding landing page.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
### `GET /onboard`
|
||||
Returns the onboarding form page.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
### `GET /screen/{slug}`
|
||||
Returns the rendered player page for a screen.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
### `GET /api/onboarding/status`
|
||||
Returns the persisted onboarding status for a device.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
Query fields:
|
||||
|
||||
@@ -36,19 +33,48 @@ Query fields:
|
||||
|
||||
### `GET /api/onboarding/screens`
|
||||
Returns the list of screens available for onboarding.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
### `GET /api/onboarding/qr`
|
||||
Returns an SVG QR code that points to the onboarding form.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
Query fields:
|
||||
|
||||
- `deviceId` required
|
||||
|
||||
### `GET /api/screens/{slug}/playlist`
|
||||
Returns the current playlist payload for a screen.
|
||||
|
||||
Response fields:
|
||||
|
||||
- `screen`
|
||||
- `playlist`
|
||||
- `slides`
|
||||
- `rssFeeds`
|
||||
- `apiSources`
|
||||
- `revision`
|
||||
|
||||
### `GET /api/screens/{slug}/connections`
|
||||
### `GET /api/screens/{slug}/clients`
|
||||
Returns the live player connection snapshot for a screen.
|
||||
|
||||
This endpoint is public within the trusted player deployment, but it exposes live connection state.
|
||||
|
||||
Response fields:
|
||||
|
||||
- `screen`
|
||||
- `screenSlug`
|
||||
- `count`
|
||||
- `connections`
|
||||
- `degraded`
|
||||
|
||||
## 🔑 Secure Endpoints
|
||||
|
||||
These endpoints are intended for internal use or shared-secret-backed requests.
|
||||
|
||||
### `POST /api/auth/page`
|
||||
Renews the current page-auth token before it expires.
|
||||
Access: internal to the player page and onboarding page. The request must include a valid `x-pulse-page-auth` header.
|
||||
|
||||
The request must include a valid `x-pulse-page-auth` header.
|
||||
|
||||
Response fields:
|
||||
|
||||
@@ -58,7 +84,6 @@ Response fields:
|
||||
|
||||
### `POST /api/onboarding`
|
||||
Binds a device to a screen and client name.
|
||||
Access: internal-only. Protect this endpoint if the player service is reachable outside your trusted network.
|
||||
|
||||
Accepted request fields:
|
||||
|
||||
@@ -78,19 +103,15 @@ Response fields:
|
||||
|
||||
### `GET /api/media/config`
|
||||
Returns the upload directory configured for the player service.
|
||||
Access: internal-only.
|
||||
|
||||
### `PUT /api/media/{filename}`
|
||||
Writes an uploaded file into the player upload directory.
|
||||
Access: internal-only and write-protected behind your deployment boundary.
|
||||
|
||||
### `DELETE /api/media/{filename}`
|
||||
Deletes a file from the player upload directory.
|
||||
Access: internal-only and write-protected behind your deployment boundary.
|
||||
|
||||
### `GET /api/rtmp/session`
|
||||
Creates or reuses an RTMP-to-HLS session for a source URL.
|
||||
Access: internal-only.
|
||||
|
||||
Query fields:
|
||||
|
||||
@@ -99,41 +120,12 @@ Query fields:
|
||||
|
||||
### `GET /api/rtmp/streams/{key}/index.m3u8`
|
||||
Returns the RTMP session HLS manifest.
|
||||
Access: internal-only.
|
||||
|
||||
### `GET /api/rtmp/streams/{key}/{fileName}`
|
||||
Returns an RTMP HLS segment or related stream file.
|
||||
Access: internal-only.
|
||||
|
||||
### `GET /api/screens/{slug}/playlist`
|
||||
Returns the current playlist payload for a screen.
|
||||
Access: public within the trusted player deployment.
|
||||
|
||||
Response fields:
|
||||
|
||||
- `screen`
|
||||
- `playlist`
|
||||
- `slides`
|
||||
- `rssFeeds`
|
||||
- `apiSources`
|
||||
- `revision`
|
||||
|
||||
### `GET /api/screens/{slug}/connections`
|
||||
### `GET /api/screens/{slug}/clients`
|
||||
Returns the live player connection snapshot for a screen.
|
||||
Access: public within the trusted player deployment, but it exposes live connection state.
|
||||
|
||||
Response fields:
|
||||
|
||||
- `screen`
|
||||
- `screenSlug`
|
||||
- `count`
|
||||
- `connections`
|
||||
- `degraded`
|
||||
|
||||
### `POST /api/screens/{slug}/commands`
|
||||
Sends a command to the player connections for a screen.
|
||||
Access: internal-only. The admin dashboard should remain the protected control surface for commands.
|
||||
|
||||
Accepted request fields:
|
||||
|
||||
@@ -157,8 +149,6 @@ Supported commands:
|
||||
- `blackout`
|
||||
- `previous`
|
||||
- `next`
|
||||
- `left`
|
||||
- `right`
|
||||
- `setclientname`
|
||||
|
||||
If `connectionId` or `clientId` is provided, the command targets a single player connection. Otherwise it is broadcast to all connections for that screen.
|
||||
@@ -254,64 +244,3 @@ Response fields:
|
||||
- `connectionId`
|
||||
- `sent`
|
||||
- `degraded`
|
||||
|
||||
## Data Models
|
||||
|
||||
### Screen
|
||||
|
||||
- `id`
|
||||
- `name`
|
||||
- `slug`
|
||||
- `playlist_id`
|
||||
- `created_at`
|
||||
- `modified_at`
|
||||
|
||||
### Playlist
|
||||
|
||||
- `id`
|
||||
- `name`
|
||||
- `fade_between_slides`
|
||||
|
||||
### Slide
|
||||
|
||||
- `id`
|
||||
- `title`
|
||||
- `body`
|
||||
- `duration_seconds`
|
||||
- `schedule_mode`
|
||||
- `schedule_start_datetime`
|
||||
- `schedule_end_datetime`
|
||||
- `schedule_start_time`
|
||||
- `schedule_end_time`
|
||||
- `schedule_days_json`
|
||||
- `media_url`
|
||||
- `media_type`
|
||||
- `kind`
|
||||
- `template_id`
|
||||
- `template`
|
||||
- `content`
|
||||
|
||||
### Connection
|
||||
|
||||
- `id`
|
||||
- `clientId`
|
||||
- `clientName`
|
||||
- `deviceId`
|
||||
- `label`
|
||||
- `userAgent`
|
||||
- `viewport`
|
||||
- `page`
|
||||
- `currentSlide`
|
||||
- `currentSlideId`
|
||||
- `currentSlideTitle`
|
||||
- `paused`
|
||||
- `blackout`
|
||||
- `clientIp`
|
||||
- `remoteAddress`
|
||||
- `connectedAt`
|
||||
- `lastSeenAt`
|
||||
|
||||
## Notes
|
||||
|
||||
- The player API is the only surface documented here.
|
||||
- Web UI/admin routes are intentionally omitted, except where the player service itself exposes onboarding and upload endpoints.
|
||||
|
||||
+11
-8
@@ -6,29 +6,32 @@ Player service websocket base URL default for local setups: `ws://localhost:3001
|
||||
|
||||
In Docker or behind a reverse proxy, use the websocket address that matches your player service exposure.
|
||||
|
||||
This document uses OpenAPI-style sections, but stays in plain markdown.
|
||||
The websocket surface is split into a secure player control channel and a secure server snapshot channel.
|
||||
|
||||
The `PULSE_SIGNAGE_SHARED_SECRET` setting does not change the websocket message format here. It is used to sign the player control socket URL and the server-side snapshot subscription; the message payloads themselves remain the same.
|
||||
Access legend:
|
||||
|
||||
## Channels
|
||||
- 🌐 Public: available within the trusted deployment network.
|
||||
- 🔑 Secure: requires internal auth or a shared-secret-backed request.
|
||||
|
||||
## 🔑 Secure Channels
|
||||
|
||||
### `GET /ws/screens/{slug}`
|
||||
Player control channel.
|
||||
|
||||
This is the bidirectional socket used by the player page. The player sends state messages to the server, and the server sends commands back to the player.
|
||||
|
||||
Access: the player page appends a valid `auth` query parameter signed with the shared secret when one is configured. The browser page refreshes this token automatically while it is active.
|
||||
The player page appends a valid `auth` query parameter signed with the shared secret when one is configured. The browser page refreshes this token automatically while it is active.
|
||||
|
||||
### `GET /ws/screens/{slug}/events`
|
||||
Player snapshot channel.
|
||||
|
||||
This is the server-to-dashboard snapshot stream for live player connection state.
|
||||
|
||||
Access: internal-only. The web backend subscribes with signed request headers; browsers should not connect directly.
|
||||
The web backend subscribes with signed request headers; browsers should not connect directly.
|
||||
|
||||
## Player Control Channel
|
||||
|
||||
#### `state`
|
||||
### Messages from player to server
|
||||
|
||||
The player sends `state` when the socket opens and whenever playback or screen state changes.
|
||||
|
||||
@@ -116,7 +119,7 @@ Moves to the next slide.
|
||||
Updates the client name associated with the player session and onboarding record.
|
||||
The command payload should include `clientName` and may include `deviceId` when the caller is updating a specific onboarding binding.
|
||||
|
||||
## Snapshot Channel
|
||||
## 🔑 Snapshot Channel
|
||||
|
||||
### Messages from server to client
|
||||
|
||||
@@ -175,4 +178,4 @@ The snapshot channel is server-to-client only.
|
||||
## Notes
|
||||
|
||||
- This document covers only the player websocket channels.
|
||||
- Web UI/admin websocket behavior is intentionally omitted.
|
||||
- Web UI/admin websocket behavior is intentionally omitted.
|
||||
Reference in New Issue
Block a user