Documentation
SDK Authoring Guide
Handwritten SDKs must follow the published contracts exactly. This page defines the canonical sources and the required breaking behaviors on current v1 endpoints.
Canonical Contracts
Use these machine-readable endpoints as the runtime contract source:
- /api/v1/specs/asyncapi/realtime.json
AsyncAPI 2.6 realtime WebSocket contract
- /api/v1/specs/openapi/dataplane.json
OpenAPI 3 contract for the data plane HTTP API (publish, channel auth, channel queries)
Breaking Rules
- All REST API error responses are RFC 7807
application/problem+json. Rejected WebSocket upgrades answer in plain text. - SDKs parse
type,title,status, anddetail. - HMAC request signatures use canonical path only. Query strings are never signed.
- Channel filtering accepts only
filter_by_prefix. Legacyprefixis removed. - Server SDKs take a required
clusterand derive the base URL ashttps://ws-{cluster}.apinator.io. They never default to the control plane.
Conformance Gate
All handwritten SDKs are validated with shared fixture vectors for request signing, channel auth, and webhook signatures; error parsing is tested in each SDK's own suite. The Node SDK runs the fixtures from its own copy, while the Go, Python, and PHP fixture tests run only inside the monorepo and are skipped elsewhere.