Skip to main content

​
The contract

The API is additive within a version. New resources, new attributes, new event types and new optional inputs can appear at any time — that’s a normal, unannounced-in-advance improvement, not a breaking change. What never happens within a version: an existing attribute is renamed or removed, a previously optional input becomes required, a resource’s meaning changes, or a 200/201/204 response starts meaning something different than it did. If a change would break a client that’s reasonably built against the documented contract, it becomes a new version, announced ahead of time with a deprecation window. While the API is in Beta — as PracticeHub 2.0 itself is — details may still be refined; any refinement that would affect an existing client is announced in the changelog with a migration window first. In practice, “build against the documented contract” means:

Safe to assume

  • Attributes listed in GET /schema/{resource} today keep existing, with the same meaning and type
  • A resource’s id keeps referring to the same record
  • An error code you’ve seen keeps meaning the same thing
  • A status code (404, 409, 422, …) keeps being used the way Errors describes

Not safe to assume

  • That GET /schema/{resource} won’t list a new attribute tomorrow — deserialize leniently, don’t reject unknown fields
  • That an error errors object contains only the attributes you sent — new validation can add more
  • That today’s set of resources, statuses or write operations is the final one — see the changelog and roadmap
  • Undocumented behaviour: field ordering in JSON, incidental status codes not listed in Errors, or anything not asserted on this site

​
How this is enforced, not just promised

The OpenAPI document on this site isn’t hand-maintained alongside the API — it is produced from the API itself (GET /schema/{resource} and the reference always agree), and every change is checked against the published contract before release. A change that would break the contract cannot go out quietly. If the reference and the running API ever disagreed, that would be a bug, not a documentation lag.

​
How changes reach you

Every change to the contract is in the changelog, dated, newest first, marked Added for additive changes and Changed for behaviour clarifications — read it, don’t diff the OpenAPI file yourself. There’s no separate release-notes email or RSS feed today; the changelog page is the record.

​
Deprecation

Nothing is deprecated on the current version — deprecation applies to moving between versions, not to attributes disappearing out from under you mid-version. If this API is ever versioned, expect: advance notice, a running-in-parallel window, and a documented migration path.
This page describes the contract as designed and enforced, not a contractual SLA — there’s no uptime or support-response commitment documented here. If you need one for a procurement process, ask help@practicehub.io rather than assuming it from this page.