Call preparation: address, identity, and data formats

API integration does not require a source development environment. Use a backend capable of HTTPS, secret storage, JSON, streaming responses, and WebSocket when needed.

flowchart LR
    A[Pin server version] --> B[Save matching OpenAPI]
    B --> C[Create least-privilege API Token]
    C --> D[Call health and read-only APIs first]
    D --> E[Then integrate async workflows]

1. Pin the deployed version

Record the deployed version and keep its matching OpenAPI and Postman assets. Paths, fields, and enums evolve; never call an older service with a newer website contract.

2. Confirm the base address

For https://vms.example.com, business APIs start at https://vms.example.com/api/v2/, while secure RTC APIs may use /api/v2/rtc/session/. Reverse proxies must preserve HTTPS, WebSocket upgrades, request-size limits, Range, and real client address semantics.

3. Choose the correct identity

Create a separate token for each application. Record its purpose, owner, expiration, and allowed IP range. Do not share an administrator token across teams.

4. Apply consistent request rules

• Send UTF-8 JSON and timezone-aware ISO 8601 timestamps.
• Missing fields, empty strings, and null have different meanings.
• Follow declared paging defaults and never assume one call returns all records.
• Ignore newly added response fields and provide a fallback for unknown enum values.
• For non-2xx responses, keep the raw body, Content-Type, HTTP status, and TraceId.

5. Run the minimum connectivity check

Call these in order:

1. /health to confirm the network and process.
2. /api/v2/system/version to confirm the deployed contract version.
3. /api/v2/auth/me to confirm the caller, roles, and permissions.
4. One read-only business API to confirm access to the intended domain.

Stop and correct the URL, certificate, proxy, or permission at the first failing step. Do not proceed directly to device controls or recording jobs.