HAL links, RFC 7807, idempotency, pagination
Every Sumvin API — Platform API and SIS — applies the same four HTTP conventions. Once you know them, they apply everywhere.HAL _links
Every response includes a _links object with navigation and action links. (Hypertext Application Language) is the link format Sumvin uses — the caller does not hardcode URLs; they follow the links in the response.
set-primary, delete, freeze) only appear when the action is permitted for the resource’s current state.
RFC 7807 Problem Details
Every error follows RFC 7807. Theerror_code field uses the format {DOMAIN}-{STATUS}-{SEQUENCE}.
trace_id with support to debug a specific request.
Idempotency
Several create endpoints are idempotent. Creating a resource that already exists returns208 Already Reported with the existing resource, not an error. Retries are safe.
Async and pagination
- Async operations return
202 Acceptedwith a_links.selfpoll target. Poll until the operation reaches a terminal state. - List endpoints use offset-based pagination (
?offset=0&limit=50). When more results are available,nextandprevlinks appear in_links.
See also
- API conventions — the full reference
- Error handling — retry strategy and error taxonomy
- Realtime events — why polling beats pushing today