Subscribes or unsubscribes the delivery of one or more message IDs over the websocket connection. Whether to subscribe or unsubscribe is defined by the HTTP method.
Supported HTTP methods: POST, DELETE, HEAD, OPTIONS
POST /api/v1/subscribe/{websocketId}/{messageId}
Subscribes for the reception of messages with the given messageId over the websocket identified by websocketId. The requested message and all subsequent updates are sent over the websocket connection.
Returns a SubscribeList with the response body containing the message IDs which have been successfully subscribed (in this case of a single subscription the list contains either one or no message IDs).
The API call does not check if the remote M&C system can deliver a message with the given ID. Messages may become available later, this is a common situation.
Parameters:
| Parameter | Description |
|---|---|
| websocketID | Identifies the websocket to send the message and subsequent updates to. See section Websocket Communication how to obtain a websocketID and how to open a websocket. |
| messageId | Identifies the message / parameter to subscribe. Must be a complete sat-nms message identifier including the M&C ID. |
Return Codes:
| Code | Description |
|---|---|
| 201 | Success, a SubscribeList is returned with the response body containing the (single) subscribed message ID. |
| 401 | Not logged in. In this case a ApiError document is returned, describing details of the error. |
| 403 | Invalid websocketId. The websocketId referenced in the URL either does not exist or the session which sent the request does not own this websocket. An empty SubscribeList is returned with the response body. |
POST /api/v1/subscribe/{websocketId}
Subscribes for the reception of messages of multiple message IDs over a websocket. This variant of the API call expects a SubscribeList data object in the request body. This data object contains the message IDs to subscribe for.
The subscription requests are forwarded and are checked if successful one by one. The API call returns a SubscribeList in the response body containing the message IDs which have been successfully subscribed.
The API call does not check if the remote M&C system can deliver messages with the given IDs. Messages may become available later, this is a common situation.
Parameters:
| Parameter | Description |
|---|---|
| websocketID | Identifies the websocket to send the message and subsequent updates to. See section Websocket Communication how to obtain a websocketID and how to open a websocket. |
Return Codes:
| Code | Description |
|---|---|
| 201 | Success, a SubscribeList is returned with the response body containing the subscribed message IDs. |
| 401 | Not logged in. In this case a ApiError document is returned, describing details of the error. |
| 403 | Invalid websocketId. The websocketId referenced in the URL either does not exist or the session which sent the request does not own this websocket. An empty SubscribeList is returned with the response body. |
DELETE /api/v1/subscribe/{websocketId}/{messageId}
Unsubscribes the reception of messages with the given messageId over the websocket identified by websocketId.
Returns a SubscribeList with the response body containing the message IDs which have been successfully unsubscribed (in this case the list contains either one or no message IDs).
The API call does not check if there is a subscription pending for the given parameters. If a subscription is canceled which never has been done or which has been unsubscribed before, this is silently ignored.
Parameters:
| Parameter | Description |
|---|---|
| websocketID | Identifies the websocket to unsubscribe. See section Websocket Communication how to obtain a websocketID and how to open a websocket. |
| messageId | Identifies the message / parameter to unsubscribe. Must be a complete sat-nms message identifier including the M&C ID. |
Return Codes:
| Code | Description |
|---|---|
| 200 | Success, a SubscribeList is returned with the response body containing the (single) unsubscribed message ID. |
| 401 | Not logged in. In this case a ApiError document is returned, describing details of the error. |
| 403 | Invalid websocketId. The websocketId referenced in the URL either does not exist or the session which sent the request does not own this websocket. An empty SubscribeList is returned with the response body. |
DELETE /api/v1/subscribe/{websocketId}
Unsubscribes the reception of multiple message IDs over a websocket. This variant of the API call expects a SubscribeList data object in the request body. This data object contains the message IDs to unsubscribe.
The subscription requests are forwarded and are checked if successful one by one. The API call returns a SubscribeList in the response body containing the message IDs which have been successfully subscribed.
The API call does not check if there are subscriptions pending for the given message IDs. If a subscription is canceled which never has been done or which has been unsubscribed before, this is silently ignored.
Parameters:
| Parameter | Description |
|---|---|
| websocketID | Identifies the websocket to unsubscribe. See section Websocket Communication how to obtain a websocketID and how to open a websocket. |
Return Codes:
| Code | Description |
|---|---|
| 201 | Success, a SubscribeList is returned with the response body containing the unsubscribed message IDs. |
| 401 | Not logged in. In this case a ApiError document is returned, describing details of the error. |
| 403 | Invalid websocketId. The websocketId referenced in the URL either does not exist or the session which sent the request does not own this websocket. An empty SubscribeList is returned with the response body. |