Skip to content

Commit 7fdb9f8

Browse files
devinbileckdevinbileck
committed
Enhance API reference in README
1 parent 50d7dde commit 7fdb9f8

1 file changed

Lines changed: 105 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -237,12 +237,111 @@ Once deployed, the following will be available:
237237

238238
## API Reference
239239

240+
The bisq-relay exposes provider-specific endpoints for sending encrypted push notification payloads to APNs and FCM.
241+
242+
### Endpoints
243+
244+
| Method | Endpoint | Provider | Description |
245+
|--------|---------------------------------|----------|-------------------------------------------|
246+
| `POST` | `/v1/apns/device/{deviceToken}` | APNs | Sends a notification to an iOS device |
247+
| `POST` | `/v1/fcm/device/{deviceToken}` | FCM | Sends a notification to an Android device |
248+
249+
Both endpoints use the same request body format.
250+
251+
### Path Parameters
252+
253+
| Parameter | Type | Required | Description |
254+
|---------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
255+
| `deviceToken` | string | yes | Provider-specific device token identifying the target device. For APNs, this is the APNs device token. For FCM, this is the FCM registration token. |
256+
257+
### Headers
258+
259+
| Header | Required | Value | Description |
260+
|----------------|----------|--------------------|----------------------------------------------------|
261+
| `Content-Type` | yes | `application/json` | Request body must be JSON. |
262+
| `Accept` | no | `application/json` | Indicates that the client accepts a JSON response. |
263+
240264
### Request Body
241265

242-
The `POST /v1/apns/device/{deviceToken}` and `POST /v1/fcm/device/{deviceToken}` endpoints accept a JSON body with the following fields:
266+
```json
267+
{
268+
"encrypted": "...",
269+
"isUrgent": false,
270+
"isMutableContent": false
271+
}
272+
```
273+
274+
| Field | Type | Required | Default | Description |
275+
|--------------------|---------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
276+
| `encrypted` | string | yes | — | Encrypted notification payload to relay to the target device. This value should already be encrypted by the sender; the bisq-relay does not decrypt, validate, or interpret the encrypted message contents. |
277+
| `isUrgent` | boolean | no | `false` | When `true`, sends the notification as a high-priority alert. When `false`, sends it as a background notification where supported by the provider. |
278+
| `isMutableContent` | boolean | no | `false` | APNs only. When `true`, sets the `mutable-content` flag in the APNs payload, allowing the iOS app's Notification Service Extension to modify the notification before display, for example for client-side decryption. This field is ignored for FCM requests. |
279+
280+
### Example APNs Request
281+
282+
```bash
283+
curl -X POST "http://127.0.0.1:8080/v1/apns/device/<device-token>" \
284+
-H "Content-Type: application/json" \
285+
-H "Accept: application/json" \
286+
-d '{
287+
"encrypted": "<encrypted-payload>",
288+
"isUrgent": true,
289+
"isMutableContent": true
290+
}'
291+
```
292+
293+
### Example FCM Request
294+
295+
```bash
296+
curl -X POST "http://127.0.0.1:8080/v1/fcm/device/<device-token>" \
297+
-H "Content-Type: application/json" \
298+
-H "Accept: application/json" \
299+
-d '{
300+
"encrypted": "<encrypted-payload>",
301+
"isUrgent": false
302+
}'
303+
```
304+
305+
### Successful Response
306+
307+
If the provider accepts the notification, the bisq-relay returns `200 OK` with a JSON response body.
308+
309+
```json
310+
{
311+
"wasAccepted": true,
312+
"isUnregistered": false
313+
}
314+
```
315+
316+
### Provider Rejection Response
317+
318+
If the request is valid but the push provider rejects the notification, the relay returns `400 Bad Request` with
319+
provider result details when available.
320+
321+
```json
322+
{
323+
"wasAccepted": false,
324+
"errorCode": "BadDeviceToken",
325+
"errorMessage": "The device token is invalid.",
326+
"isUnregistered": true
327+
}
328+
```
329+
330+
| Field | Type | Description |
331+
|------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
332+
| `wasAccepted` | boolean | Indicates whether the upstream push provider accepted the notification. |
333+
| `errorCode` | string | Provider error code, when available. Omitted when there is no provider error code. |
334+
| `errorMessage` | string | Provider error message, when available. Omitted when there is no provider error message. |
335+
| `isUnregistered` | boolean | Indicates whether the target device token is no longer registered with the push provider. Clients should treat this as a signal that the token may need to be removed or refreshed. |
336+
337+
### Request Error Responses
338+
339+
Request-level errors return an HTTP status code with an empty response body.
243340

244-
| Field | Type | Required | Default | Description |
245-
|--------------------|---------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
246-
| `encrypted` | string | yes | — | Encrypted notification payload |
247-
| `isUrgent` | boolean | no | `false` | When `true`, sends as high-priority alert; when `false`, sends as background notification |
248-
| `isMutableContent` | boolean | no | `false` | APNs only. When `true`, sets the `mutable-content` flag in the APNs payload, allowing the iOS app's Notification Service Extension (NSE) to modify the notification content before display (e.g. for client-side decryption) |
341+
| Status | Cause |
342+
|------------------------------|-----------------------------------------------------------------------------------------------------|
343+
| `400 Bad Request` | Missing or invalid request body, malformed JSON, validation failure, or invalid request parameters. |
344+
| `404 Not Found` | Endpoint does not exist or the device token path parameter is missing. |
345+
| `405 Method Not Allowed` | Endpoint exists but does not support the requested HTTP method. |
346+
| `415 Unsupported Media Type` | Request body does not use `Content-Type: application/json`. |
347+
| `500 Internal Server Error` | Unexpected relay error while processing the notification. |

0 commit comments

Comments
 (0)