Proximity Identity Backend API Documentation

Base URL: /api (example) Auth: Currently relies on device headers (x-device-sig, x-ws-token) and IP-based identification for proximity features.

Models:

• Identity: Contains identity_info and inventory arrays.
• DeviceScan: Records devices’ last scan (SSID info, timestamp, etc.).

1. Common Headers

| Header | Description | Required | | -------------- | -------------------------- | -------------------------------------- | | x-device-sig | Unique device signature | Optional (used in proximity detection) | | x-ws-token | Session or workspace token | Optional | | public_ip | Client IP address | Optional |

3. Identity Endpoints

3.1 Get Identity by ID

GET /identity/:identityId

| Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------- | | identityId | String | Yes | Identity identifier |

Response: Identity object including identity_info and inventory.

Error Codes:

| Status | Message | | ------ | --------------------- | | 404 | Identity not found | | 500 | Internal server error |

3.2 Get Identity by Phone Number

GET /identity?phoneNumber=<phoneNumber>

| Query Parameter | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | phoneNumber | String | Yes | Identity contact number |

Response: Identity object.

Error Codes:

| Status | Message | | ------ | --------------------------------------- | | 400 | phoneNumber query parameter is required | | 404 | Identity not found | | 500 | Internal server error |

3.3 Create / Update / Delete Identity

| Method | Endpoint | Request Body | Response | Notes | | ------ | ------------------- | ------------------------------------------------------------------------------- | ------------------- | ------------------------------- | | POST | /identity | { identity_id, name, address, contact, gps_location, opening_hours, inventory } | 201, identity created | Create new identity | | PUT | /identity/:identityId | { field: value, ... } | 200, updated identity | Partial update supported | | DELETE | /identity/:identityId | None | 200, deleted identity | Remove identity and all inventory |

4. Error Response Format

| Field | Type | Description | | --------- | ------ | ------------------------------------------------ | | error | String | Error message | | message | String | Optional descriptive message for success/failure |

Example:

{
  "error": "Identity not found"
}

5. Notes / Guidelines

1. Proximity detection: GET /identities uses device signature, token, or IP as a fallback to retrieve recent Wi-Fi scans.
2. Bulk operations: Partial success is possible; the response includes per-item update status.
3. Consistency: All update operations return the new state of the object after modification.
4. Pagination: Not implemented yet for search; consider adding limit and offset query params for large datasets.
5. Logging: Server logs device signatures and SSIDs for audit/debugging.