Connection lifecycle
Every message is a JSON text frame with the same envelope. Binary frames, invalid JSON and messages over 4,096 bytes close the connection with 4002.
{ "op": 0, "d": {}, "s": 42, "t": "OPPORTUNITY_CREATE" }op is the opcode and d is the payload. s and t appear only on op 0, which carries events: s is the sequence number and t is the event name. s is null on READY and RESUMED.
The address is wss://gateway.apprenticewizard.co.uk/v1. A different version in the path closes with 4013.
What data is sent
Your client sends three things, and nothing else:
- IDENTIFY carries your token. This is the only message with the token in it.
- HEARTBEAT carries
last_seq, the sequence number of the last event you processed, or null. - RESUME carries the
session_idfrom READY andseq, the sequence number of the last event you processed. It has no token.
The server sends:
- HELLO with the heartbeat interval, and HEARTBEAT_ACK with no data.
- READY with your
session_idandhead_seq, and RESUMED with no data. - INVALID_SESSION with
resumableset to false, and RECONNECT with no data. - OPPORTUNITY_CREATE events. Each carries an event id, a timestamp and a summary of one opportunity:
id,title,employer,location,type,closing_dateandurl.
An event describes an opportunity, not a person. The same events go to every connected client, and none of them contains personal data about you or anyone else. The opcodes and events pages list every field with its type.
1. Connect and receive HELLO
The server sends HELLO (op 10) first, with the heartbeat interval in milliseconds:
{ "op": 10, "d": { "heartbeat_interval": 45000 } }2. Identify
Send IDENTIFY (op 2) within 30 seconds of connecting. If you do not, the connection closes with 4003.
{ "op": 2, "d": { "token": "<your token>" } }3. Receive READY
When the token is valid, the server sends a READY event:
{ "op": 0, "t": "READY", "s": null, "d": { "session_id": "...", "head_seq": 1234 } }Store session_id the way you store the token, because it lets you resume without sending the token again. head_seq is the sequence number of the newest event at that moment. A new session starts there and receives no history.
4. Send heartbeats
Send HEARTBEAT (op 1) once every interval, with the sequence number of the last event you processed, or null if you have not received one yet:
{ "op": 1, "d": { "last_seq": 1234 } }The server answers with HEARTBEAT_ACK (op 11). The server may also send a heartbeat of its own. Answer it straight away with a heartbeat of yours.
If two intervals pass with no heartbeat from you, the server closes the connection with 4009.
5. Handle events
Each event arrives as op 0. Process events in the order they arrive. See events. Delivery can repeat an event, so ignore an event whose d.id you have already handled. See repeats and stable identifiers.
6. Handle a close
The server ends a connection with a close code from 4000 to 4015. The close codes page says whether each one allows you to reconnect. For the ones that do, resume instead of identifying again. This includes closes caused by a deploy.
Sometimes the server refuses a connection before sending anything. For close codes 4008, 4013, 4014 and 4015 you may see the connection accepted and then closed at once, with no HELLO. 4013 means the path is not /v1.
The server may send RECONNECT (op 7). Reconnect and resume.
Constants
| Value | Figure |
|---|---|
| Heartbeat interval | 45 seconds |
| Time to send IDENTIFY | 30 seconds |
| Largest message from a client | 4,096 bytes |