Sign in to see your venue's slug and publishable key in every sample.
Your account has no venue yet, so the samples keep their placeholders. Sign out
Signed in as · . Create a publishable key in the console and reload to see it here. Sign out
Signed in as · . The samples show your venue's publishable key. Sign out
Developer docs
Versioning and compatibility
What a BookDinePlay version number means, which changes can arrive unannounced, what we promise for API, SDKs, plugin and MCP, and how deprecation works.
You build on BookDinePlay so that it keeps working while we keep improving it. This page says exactly what we promise, what can change without warning, and how you hear about what will break. Every promise here is either enforced by a test in our build or by the release process; where it is not, we say so.
What a version number means
BookDinePlay is released as one numbered set, tagged vX.Y.Z on GitHub. The same number names everything that ships to you:
| Artifact | Where the version shows |
|---|---|
| JavaScript SDK | The CDN path cdn.bookdineplay.com/sdk/<version>/bookdineplay.js |
| .NET packages | BookDinePlay.Sdk and BookDinePlay.Shared on nuget.org |
| WordPress plugin | bookdineplay-<version>.zip on the GitHub release |
| API and MCP server | Deployed with the release; the API has no version in its URL |
A version with a - in it (for example 0.24.0-rc.1) is a pre-release. A pre-release is published only under its exact version path: it never moves the CDN's major-line alias, and it is not listed in the changelog.
Read the number as major.minor.patch. A patch fixes behaviour without changing what you can call. A minor adds capability and can append to contracts, as explained below. A major is the only release that may break something you built against what this documentation describes.
What the promise covers
The promise covers what this documentation describes: the routes under API reference, the problem types in Errors, the options and methods of the JavaScript SDK, the .NET SDK with its contracts, the shortcodes and attributes of the WordPress plugin, and the tools and prompts of the MCP server. Anything not described here — an internal route, the console's own interface, a field you found in a response that no page names — can change in any release.
Changes that can reach you in any release
These are not breaking, and your integration must tolerate them:
- New routes, new optional request fields and new response fields. Ignore fields you do not know.
- New values where a field is a set of named values: a reservation or ticket status, a resource type, the
reasonof a refusal, a problem type, a plan's feature. Handle an unknown value gracefully rather than failing. - New optional parameters on SDK methods, new SDK methods, new widget options, new shortcode attributes, new MCP tools and prompts.
- Stricter protection of the platform: a rate limit is the standing example. It will be announced in advance, never switched on silently, and signalled the standard way (
429withRetry-After) — see Rate limits.
One consequence needs a plain warning. The .NET SDK reads named values strictly: a status it does not know makes deserialisation throw a JsonException, rather than hand you a surprise string. The release that introduced the PaidButUnavailable reservation status is the example, and it is why the changelog always says when a release adds such a value and which SDK version you need. Keep the SDK reasonably current; the JavaScript SDK passes unknown values through.
What counts as breaking
A change is breaking when something that worked as documented stops working. In particular: removing or renaming a route, a field, an SDK method, an option or a tool; changing the type of a field; changing the meaning of a status or the status code of a refusal; making an optional request field required; narrowing what a limit documented in the reference allows. Breaking changes are marked Breaking in the changelog, are rare, and from version 1.0 happen only in a new major version, after the deprecation period below.
The published contracts
BookDinePlay.Shared — the request and response types the SDK and the API share — ships on nuget.org, so a change to one is a change to a public interface with consumers outside this repository. What we promise:
BookDinePlay.Sharedpromises source compatibility and JSON compatibility. Recompilation is required across a minor bump. Dropping a newer assembly in next to a consumer compiled against the older one, without recompiling, is explicitly not supported.
How that works, so you can plan around it. Contracts are positional records, and they grow by appending trailing optional parameters. Appending replaces the record's constructor and Deconstruct with longer ones: your source still compiles, because the new parameters are optional, and an old payload still deserialises, because absent members take their default. Only an assembly that was already compiled notices, as a MissingMethodException at run time — which is why you recompile when you update the package.
Within that, we never insert a parameter in the middle, never rename a member, never change a member's type, and never make an existing member required. A constant such as a maximum length is compiled into your assembly, so narrowing one changes nothing for you until you rebuild.
This is not left to goodwill: a test writes the whole public surface of BookDinePlay.Shared to an approved snapshot and fails the build on any change, saying whether it is an append or an incompatibility. Approving that snapshot is the public-API review. The test also replays the payload every earlier shape of each record would have sent, to prove the members that were there still come back unchanged. What it does not check is binary compatibility, because that is not promised.
The JavaScript SDK and the CDN
The CDN serves the SDK under two path shapes with different guarantees:
| Path | Content | Cache |
|---|---|---|
sdk/<version>/bookdineplay.js |
One exact release. Immutable: its bytes never change | One year |
sdk/v<major>/bookdineplay.js |
The latest release of that major line | Five minutes |
Use the alias when you want fixes without touching your page. A new major version gets its own alias (sdk/v1/ after sdk/v0/), and the old alias keeps serving the last release of its line: an alias never jumps to a new major version, so your page changes major version only when you change the path. Pin an exact version with its integrity hash when your policy demands byte-for-byte reproducibility. The hash is published next to the file as sdk/<version>/sri.txt and on the GitHub release, only ever for an exact version — never for the alias, whose content changes by design. See CDN for the details.
Deprecation
When something will be removed, you hear about it first and have time to move:
- Announced. The release that deprecates it lists it in the changelog under Deprecated, naming the replacement, and the reference page for the item says so. In the .NET SDK the member is marked
[Obsolete]with the replacement in its message. - Still working. A deprecated item keeps working, unchanged, for at least six months after the release that announced it, and it is never removed in a release that is not a new major version.
- Removed. The removal is listed under Breaking in the changelog of the major release that does it.
The only exception is a security or legal reason that does not allow waiting. In that case the change is announced the same day, with the reason, and the changelog says that the period was shortened.
How you find out
- The changelog lists every stable release, newest first, with everything an integration can notice. A stable release is not published without its entry: the release process refuses a stable tag that has no section for its version in both languages.
- Each GitHub release links the packages and the SDK's integrity hash.
- The Compatibility section of the
BookDinePlay.Sharedpackage readme repeats the contract promise above where a package consumer will see it.