Skip to main content

​
Current version

v1. All endpoints live under https://api.novatrade24.com/v1/.... The spec document is openapi-integration-v1.yaml.

​
Version in URL path

We use URL-path versioning (/v1/) rather than headers. Reasons:
  • Cacheable, bookmarkable, copy-pasteable.
  • Obvious in logs and error reports.
  • Trivially routable at edge.
  • Matches Stripe/GitHub/Twilio convention.

​
Non-breaking vs breaking

​
Non-breaking (ship in current version, any time)

  • New endpoints.
  • New optional request fields.
  • New response fields.
  • New enum values on fields where the schema documents “may add values”.
  • New error problem types.
  • New webhook event types.
  • Increased rate limits.
Your client must ignore unknown fields and must accept unknown enum values gracefully — wire this assumption into your deserialization.

​
Breaking (requires new major version)

  • Removing endpoints or fields.
  • Renaming fields.
  • Changing response types.
  • Removing enum values.
  • Tightening constraints (stricter validation on existing fields).
  • Changing auth flow.
  • Changing the signature algorithm on webhooks (bumps webhook schemaVersion in parallel).
Breaking changes ship as v2 on a new URL path (/v2/...).

​
Deprecation policy

  • Breaking changes are announced at least 12 months before removal.
  • v1 remains available for at least 12 months after v2 launches.
  • Deprecated endpoints return Deprecation: true and Sunset: <date> headers (RFC 8594) on every response during the overlap period.
  • Changelog entries flag deprecated features explicitly.
Example headers on a deprecated endpoint: 
Deprecation: true
Sunset: Sat, 15 Apr 2028 00:00:00 GMT
Link: <https://developers.novatrade24.com/v2/buyers>; rel="successor-version"

​
Schema version on webhooks

Webhook payloads carry a schemaVersion integer separate from the URL version. Rationale: we may need to evolve the data payload for a single event type without a full major bump.
  • Register the schema versions you accept via acceptedSchemaVersions on the webhook endpoint ([1] by default).
  • When we ship schemaVersion: 2 for an event, we dual-emit for a 6-month deprecation window.
  • Your endpoint receives the highest supported version.

​
Client compatibility requirements

Any API client you build or consume must:
  1. Ignore unknown JSON fields. Jackson NON_NULL + FAIL_ON_UNKNOWN_PROPERTIES=false; Pydantic with extra='ignore'; TypeScript with loose typing on response types.
  2. Accept unknown enum values. Treat them as “opaque string” and log
    • continue. Never throw on unknown values for our documented enums.
  3. Observe response headers. Deprecation, Sunset, X-RateLimit-* — your monitoring should surface these.
  4. Respect media types. Always application/json for requests/responses except multipart uploads and application/problem+json for errors.

​
Detecting deprecation in CI

Add to your CI pipeline: 
# Fail if a deprecated endpoint is in use.
resp=$(curl -sI -X GET "https://api.novatrade24.com/v1/..." -H "Authorization: Bearer $T")
if echo "$resp" | grep -qi "^Deprecation: true"; then
  echo "ERROR: using deprecated endpoint" >&2
  exit 1
fi
Or subscribe to the changelog feed — we publish machine-readable entries.

​
Next

Changelog

What changed and when.

Error reference

Problem-type stability guarantees.