Subscriptions API Reference

This page documents the Subscriptions endpoints in the DTS (Device Token Service) API.

Store or Update Device Subscription

Stores or updates an FCM device token for push notifications for a specific place.

URL: /dts/places/{placeId}/subscriptions

Method: PUT

Auth required: Yes

Path Parameters:

Request Body:

Example Request:

curl -X PUT "https://api.uos.example.com/dts/places/1ee68c4e-7008-4227-a92d-e1b13ac64f30/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
  }'

Success Response:

• Code: 200 OK
• Content:

{
  "status": 200,
  "responseType": "success",
  "message": {
    "message": "Device subscription created/updated successfully",
    "error": null,
    "data": {
      "place_id": "1ee68c4e-7008-4227-a92d-e1b13ac64f30",
      "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
    },
    "extra": null
  }
}

Error Responses:

• Code: 400 Bad Request
  • Content: { "error": "Bad Request", "message": "placeId must be a valid UUID" }
  • Content: { "error": "Bad Request", "message": "device_token is required and must be a non-empty string" }
• Code: 404 Not Found
  • Content: { "error": "Not Found", "message": "Place not found" }
• Code: 500 Internal Server Error
  • Content: { "error": "Internal Server Error", "message": "Database error" }

Delete Device Subscription

Removes an FCM device token subscription for a specific place.

URL: /dts/places/{placeId}/subscriptions

Method: DELETE

Auth required: Yes

Path Parameters:

Request Body:

Example Request:

curl -X DELETE "https://api.uos.example.com/dts/places/1ee68c4e-7008-4227-a92d-e1b13ac64f30/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
  }'

Success Response:

• Code: 200 OK
• Content:

{
  "status": 200,
  "responseType": "success",
  "message": {
    "message": "Device subscription deleted successfully",
    "error": null,
    "data": {
      "place_id": "1ee68c4e-7008-4227-a92d-e1b13ac64f30",
      "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
    },
    "extra": null
  }
}

Error Responses:

• Code: 400 Bad Request
  • Content: { "error": "Bad Request", "message": "placeId must be a valid UUID" }
  • Content: { "error": "Bad Request", "message": "device_token is required and must be a non-empty string" }
• Code: 404 Not Found
  • Content: { "error": "Not Found", "message": "Device subscription not found" }
• Code: 500 Internal Server Error
  • Content: { "error": "Internal Server Error", "message": "Database error" }

Device Token Format

Device tokens are Firebase Cloud Messaging (FCM) registration tokens that identify a specific app installation on a device. These tokens:

• Are unique to each app installation
• Can change when the app is restored on a new device, when an app is restored from a backup, or when the user uninstalls/reinstalls the app
• Should be refreshed periodically by your app and updated using the PUT endpoint

Subscription Behavior

• Upsert Logic: The PUT endpoint uses upsert logic, meaning it will create a new subscription if none exists or update an existing one if the same place and device token combination already exists
• Conflict Resolution: The system uses place_id and device_token as a composite key to prevent duplicate subscriptions
• Automatic Cleanup: Device subscriptions are automatically updated with the current timestamp whenever they are created or modified

Use Cases

Register Device for Notifications

When a user opens your app and grants notification permissions:

curl -X PUT "https://api.uos.example.com/dts/places/1ee68c4e-7008-4227-a92d-e1b13ac64f30/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
  }'

Update Token on Refresh

When your app detects the FCM token has been refreshed:

curl -X PUT "https://api.uos.example.com/dts/places/1ee68c4e-7008-4227-a92d-e1b13ac64f30/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "fXYzABC123DEF:APA91bNewTokenValue..."
  }'

Unregister Device

When a user logs out or disables notifications:

curl -X DELETE "https://api.uos.example.com/dts/places/1ee68c4e-7008-4227-a92d-e1b13ac64f30/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "eGCgkKMKFHQ:APA91bEhSO-XOvT8..."
  }'