Proposed integration design
How an app is intended to connect to DartXchange. Everything on this page is a design proposal.
Proposed / illustrative. No endpoint on this page exists yet. Paths, field names and flows are not implemented or tested and will change. Do not build against them.
Architecture
Your server talks to the DartXchange API using private credentials. Your client (web or mobile) talks only to your own server, which relays what it needs. Real-time updates and video signalling will use short-lived tokens that your server requests on a player’s behalf.
Player app (client) <-> Your server <-> DartXchange API
\ short-lived token \-> real-time / signallingAuthentication
- Public application ID — identifies your app; safe to appear in client code.
- Private credentials — issued at registration; used only on your server to sign requests or obtain access tokens. Never embed in browser or mobile code.
- Server-to-server requests are authenticated and rate limited.
Player identity
Your app passes the player’s existing username, your application reference and your own stable player ID. DartXchange creates a permanent unique player ID and derives the display name.
- Display name = username +
-+ application reference, e.g.180King-DF. - The suffix is unique to the registered application and is never typed by players.
- Matching and permissions use the permanent ID, never the display name.
Endpoints Proposed
| Purpose | Method & path (illustrative) | Notes |
|---|---|---|
| Application registration | POST /v1/applications | Initially a reviewed enquiry; issues app reference and credentials. |
| Authentication | POST /v1/auth/token | Server-side only. Returns a short-lived access token. |
| Player identification | PUT /v1/players/identify | Maps app player to a permanent DartXchange ID; returns display name. |
| Lobby discovery | GET /v1/lobbies | Filters: scoring method, format, length, availability. |
| Create a lobby | POST /v1/lobbies | Sets format and accepted scoring: automatic, manual or either. |
| Join a lobby | POST /v1/lobbies/{id}/join | Rejected if the player’s scoring method is not accepted. |
| Leave a lobby | POST /v1/lobbies/{id}/leave | |
| Match creation | POST /v1/matches | Created by DartXchange when a lobby fills. |
| Submit a visit | POST /v1/matches/{id}/visits | Requires an idempotency key to prevent duplicates. |
| Confirm a result | POST /v1/matches/{id}/result/confirm | Both sides confirm; disputes handled by policy to be defined. |
| Video signalling | WS /v1/matches/{id}/signal | Exchanges WebRTC offers, answers and ICE candidates. |
Examples Illustrative
Identify a player (server-side)
// ILLUSTRATIVE - not implemented. Runs on YOUR server only.
PUT /v1/players/identify
Authorization: Bearer <short-lived token>
{ "app_ref": "DF", "player_username": "180King", "app_player_id": "u_8431" }
// response
{ "player_id": "dxp_permanent_id", "display_name": "180King-DF" }
Create a lobby
// ILLUSTRATIVE
POST /v1/lobbies
{ "format": "501", "best_of": 5, "accepted_scoring": "either" } // "automatic" | "manual" | "either"
Submit a visit
// ILLUSTRATIVE
POST /v1/matches/{id}/visits
Idempotency-Key: <unique per visit>
{ "leg": 1, "visit_no": 7, "score": 100, "bust": false, "remaining": 261 }Shared match protocol (planned)
The protocol will standardise game format, starting score, player order, visit scores, busts, remaining score, checkout, legs and sets, match result, and disconnect/reconnect handling — so different apps can keep different scoring engines. Because manual and automatic scoring are not verified to the same standard, each match will record which method each side used.
Video signalling
Apps supply their own camera feeds. DartXchange will relay WebRTC signalling so peers can connect directly where possible. TURN relays will be provided for networks where direct connections fail; an SFU may follow for spectators and events. Nothing here is built yet.
Security requirements for the eventual backend
- Public application identifier; private server-side credentials only.
- Never expose private API secrets in browser JavaScript.
- Validate application and player identities server-side on every call.
- Prevent duplicate match events with idempotency keys.
- Authentication and rate limiting on all endpoints.
