Changelog

ROOTE separates the current API contract from its release history and its public presentation.

Canonical JSON contractCopy Anchor Link

Once published, the changelog is fetched without authentication:

GET https://api.roote.ai/changelog.json
Accept: application/json

The prepared schema has a top-level document version, a document update timestamp, and release entries ordered from newest to oldest:

{
  "version": "1",
  "updated_at": "2026-10-04T08:15:00.000Z",
  "entries": [
    {
      "id": "2026-10-04-journey-scope-boundary",
      "published_at": "2026-10-04T05:40:18.000Z",
      "api_version": "2.0.0",
      "type": "breaking",
      "title": "Journey authorization scope separated",
      "description": "Journey planning now requires journey:read while public data and departures remain under data:read. Existing observed Journey consumers were migrated explicitly.",
      "breaking": true,
      "links": [
        {
          "label": "OpenAPI document",
          "url": "https://api.roote.ai/openapi.json"
        }
      ]
    }
  ]
}

This example is validated against the prepared schema, but it does not prove that the endpoint has been deployed.

The prepared response uses an ETag for conditional requests and bounded public caching. The document is validated as a whole: duplicate IDs, invalid ordering, unsafe links, invalid dates, unsupported types, and inconsistent breaking classifications are rejected before publication.

What belongs in the changelogCopy Anchor Link

The changelog records verified changes to the public API. An internal refactor, provider implementation detail, deployment mechanism, or database change is not necessarily a public-contract change. It belongs in the public history only when it changes behavior that consumers can observe or need to act on.

Published functionality and future plans must remain separate:

• the changelog contains only changes verified in a published API release;
• planned or in-progress work belongs in a roadmap and must be labeled as future;
• OpenAPI describes the current contract, not historical states or future intentions;
• the Developer Portal presents the canonical history and must not become a second manually maintained source.

Qualifying breaking changesCopy Anchor Link

Compatibility must be assessed from the consumer's point of view. Removing an entitlement, endpoint, parameter, or response field can be breaking. Making an optional parameter or field required can also be breaking. A change must not receive breaking: false merely because automated OpenAPI comparison did not classify it as breaking.

The move of Journey authorization from data:read to journey:read is classified according to its actual effect. Existing consumers that would lose Journey access without a scope migration are affected by a breaking authorization boundary, even when observed consumers are migrated operationally. The entry should state both the contract change and the mitigation actually performed.

CI may detect OpenAPI differences and propose a review, but a human validates the public description, classification, migration guidance, and links.

Release procedureCopy Anchor Link

1. Update the API contract when the public behavior requires it. Preserve the existing OpenAPI generation pipeline instead of copying generated schemas into documentation.
2. Write the canonical changelog entry and have its wording, stable ID, dates, API version, type, breaking value, migration impact, and public HTTPS links reviewed.
3. Run type checking, tests, the production build, changelog validation, and applicable OpenAPI compatibility controls.
4. Publish the API, generated OpenAPI document, and canonical changelog in the same release artifact.
5. Verify the release API, https://api.roote.ai/openapi.json, https://api.roote.ai/changelog.json, JSON headers, links, and conditional ETag behavior.
6. Synchronize the verified canonical document to the Developer Portal using the dedicated server-side integration and idempotency key.
7. Verify the public presentation at https://dev.roote.ai/changelog, including ordering, labels, breaking status, dates, versions, descriptions, and links.

Portal synchronization is downstream of the API release. A synchronization outage does not mean that a healthy API release failed, and it must not roll back that release or delete portal history. The same canonical document can be replayed safely after the portal integration recovers.

Pending publication workCopy Anchor Link

The following items are not yet verified in production:

• publish the canonical JSON route and its validation code with an API release;
• verify the public JSON response, cache headers, ETag, ordering, and links;
• configure the dedicated server-side portal ingestion URL and machine secret;
• complete a real post-release synchronization;
• verify that the Developer Portal renders only synchronized canonical entries.

Keep this status explicit until each public check succeeds.