Hodoflow / Developers
Sign in
Browse documentation
Help Center →
Concept All API surfaces

Versioning and changelog

Understand Hodoflow's surface-specific compatibility policy, response version headers, deprecation signals, and release-matched artifacts.

View as Markdown

Hodoflow versions each public surface according to its transport. There is no single header that changes every API at once.

Current public versions

Surface Current identity Evidence
JSON:API v1 /api/json/v1 path and x-api-version: v1
GraphQL 2026-07-05 x-api-version and first line of schema.graphql
Token exchange v1 route family /api/v1/oauth/token
Webhook ingestion v1 route family /api/v1/webhooks/:token

The version returned by a response is the authoritative identity of that surface. Store it with x-request-id in diagnostics.

JSON:API compatibility

JSON:API uses major path versioning. Additive fields and operations can enter v1; clients must ignore attributes they do not consume. A breaking request or response change requires a new mount such as /api/json/v2 and a migration window for v1.

Use stable operationId values from OpenAPI JSON when mapping generated clients or tests. A path can contain a version while the application origin in servers remains unversioned; join them exactly once.

GraphQL compatibility

GraphQL evolves additively at one /api/graphql endpoint. New fields are compatible for clients that select explicitly. A field or argument scheduled for removal is marked deprecated in schema introspection and the generated SDL before the deprecation window closes. The date version advances when a schema compatibility boundary changes.

The schema currently exposes no mutations or subscription fields. Do not build against internal types or infer capabilities that are absent from the SDL.

Deprecations

Legacy token and webhook URLs containing an organization domain are deprecated. Use the canonical apex paths shown in Base URLs. Deprecation warnings in server logs are not a client-facing migration channel; public changes must appear in release notes and the versioned artifacts.

Release-matched changelog workflow

This portal does not invent a release history separate from the product. For each deployed release:

  1. compare the committed GraphQL SDL with the generated schema;
  2. regenerate and contract-test OpenAPI operation IDs, scopes, examples, and errors;
  3. update affected guides and reference metadata in the same change;
  4. verify old HTML and Markdown aliases; and
  5. publish product release notes naming additions, deprecations, and migration deadlines.

Until a dedicated release-note feed is published, the current OpenAPI, GraphQL SDL, and this page are the honest compatibility sources. Never claim a capability merely because a future route name appears in planning material.

Related documentation