187 lines
3.6 KiB
Markdown
187 lines
3.6 KiB
Markdown
# IEM Alerter WebSocket API Documentation
|
|
|
|
WebSocket Endpoint: `/iem`
|
|
|
|
This WebSocket endpoint allows clients to subscribe to weather-related channels,
|
|
receive real-time updates, and manage their subscriptions.
|
|
|
|
## Legal Disclaimer
|
|
|
|
This system is not intended to be used for, or as a supplement for information regarding life or death situations. For critical weather-related information, please rely on official sources such as National Weather Service radio stations, local radio or news outlets, and local emergency management agencies.
|
|
|
|
## Connection
|
|
Upon connecting to the `/iem` WebSocket endpoint, the server will send a connection-info message
|
|
containing the following details:
|
|
|
|
```json
|
|
{
|
|
"type": "connection-info",
|
|
"state": true,
|
|
"uuid": "<unique-identifier>",
|
|
"host": "<server-hostname>"
|
|
}
|
|
```
|
|
|
|
## Supported Message Types
|
|
|
|
### 1. Subscribe to a Channel
|
|
Clients can subscribe to a specific channel or all channels.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"type": "subscribe",
|
|
"channel": "<channel-name>" // Optional, subscribe to all channels if omitted
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
- Success:
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 200,
|
|
"data": {
|
|
"message": "Subscribed to <channel-name>"
|
|
}
|
|
}
|
|
```
|
|
- Failure (Invalid Channel):
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 404,
|
|
"data": {
|
|
"error": "Invalid channel."
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Unsubscribe from a Channel
|
|
Clients can unsubscribe from a specific channel or all channels.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"type": "unsubscribe",
|
|
"channel": "<channel-name>" // Optional, unsubscribe from all channels if omitted
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
- Success:
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 200,
|
|
"data": {
|
|
"message": "Unsubscribed from <channel-name>"
|
|
}
|
|
}
|
|
```
|
|
- Failure (Invalid Channel):
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 404,
|
|
"data": {
|
|
"error": "Invalid channel."
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Get Current Subscriptions
|
|
Clients can request a list of their current subscriptions.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"type": "get-subscriptions"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 200,
|
|
"data": {
|
|
"subscriptions": ["<channel-name-1>", "<channel-name-2>"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Get Room List
|
|
Clients can request a list of available rooms.
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"type": "room-list"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
- Success:
|
|
```json
|
|
{
|
|
"type": "room-list",
|
|
"code": 200,
|
|
"count": <number-of-rooms>,
|
|
"data": ["<room-name-1>", "<room-name-2>"]
|
|
}
|
|
```
|
|
- Failure (No Rooms Available):
|
|
```json
|
|
{
|
|
"type": "room-list",
|
|
"code": 503,
|
|
"count": 0,
|
|
"data": {
|
|
"error": "Room list is currently empty. Please try again later."
|
|
}
|
|
}
|
|
```
|
|
|
|
## Real-Time Updates
|
|
When subscribed to a channel, clients will receive real-time updates in the following format:
|
|
|
|
**Message:**
|
|
```json
|
|
{
|
|
"type": "iem-message",
|
|
"data": {
|
|
"channel": {
|
|
"location": "<location-name>",
|
|
"room": "<room-name>"
|
|
},
|
|
"event": {
|
|
"name": "<event-name>",
|
|
"priority": <priority-level>,
|
|
"code": "<event-code>"
|
|
},
|
|
"body": "<message-body>",
|
|
"timestamp": "<timestamp>",
|
|
"wmo": "<wmo-code>",
|
|
"pil": "<pil-code>",
|
|
"station": "<station-name>",
|
|
"raw": "<raw-product-id>",
|
|
"rawBody": "<raw-message-body>",
|
|
"image": "<image-url>", // Optional
|
|
"productText": "<product-text>" // Optional
|
|
}
|
|
}
|
|
```
|
|
The Priority level is a number from 1 to 5, 1 being the loest priority and 5 being the highest. These priority levels are defined per alert type by the developers of the IEM alerter system.
|
|
|
|
## Error Handling
|
|
If an error occurs, the server will send an error response:
|
|
```json
|
|
{
|
|
"type": "internal-response",
|
|
"code": 500,
|
|
"data": {
|
|
"error": "Internal server error."
|
|
}
|
|
}
|
|
``` |