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:

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, and detail.
  • HMAC request signatures use canonical path only. Query strings are never signed.
  • Channel filtering accepts only filter_by_prefix. Legacy prefix is removed.
  • Server SDKs take a required cluster and derive the base URL as https://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.