Conventions
Addressing, JSON, identifiers, cursors, and retry rules for Product HTTP.
The following rules apply to the currently published Product HTTP operations.
Addressing and format
| Convention | Behavior |
|---|---|
| Base URL | Local example: http://127.0.0.1:5001; all paths start at / |
| Request | POST uses UTF-8 JSON; /route uses GET query parameters |
| Response | JSON; endpoints do not share a universal envelope |
| UID / Channel ID | Strings owned by the product |
| Channel | Identified by channel_id plus channel_type |
| Message sequence | Ordered only within one Channel |
Check HTTP status first, then parse the endpoint-specific schema. Do not force responses into a universal {data,error} type.
Identifiers and cursors
uidis a product identity, not a nickname, connection ID, or device ID.- The client view of a person Channel uses the peer UID.
message_seqis a per-Channel cursor; JavaScript should preservemessage_idstrto avoid large-integer precision loss.next_cursoris opaque. Echo it unchanged untildone=true.
Retries
| Operation | Rule |
|---|---|
/route | Back off and retry network failures or temporary 5xx |
/user/token | Retry the same identity intent; do not mint tokens in a loop |
/channel/messagesync | Retry with the same cursor and tolerate overlap with realtime delivery |
| Channel mutation | Retry only while the product intent remains valid; treat reset and remove-all with care |
/conversation/list | Echo next_cursor unchanged and stop only at done=true |
/conversation/retry | Retry only the bounded unresolved keys returned by the API |
These operations define no universal Idempotency-Key. See Authentication & Security for security requirements and Error Responses for failure classification.