Anmelden um den Slug und den veröffentlichbaren Schlüssel Ihrer Location in jedem Beispiel zu sehen.
Ihr Konto hat noch keine Location, die Beispiele behalten daher ihre Platzhalter. Abmelden
Angemeldet als · . Legen Sie in der Konsole einen veröffentlichbaren Schlüssel an und laden Sie die Seite neu, um ihn hier zu sehen. Abmelden
Angemeldet als · . Die Beispiele zeigen den veröffentlichbaren Schlüssel Ihrer Location. Abmelden
Entwicklerdokumentation
Versionierung und Kompatibilität
Was eine BookDinePlay-Versionsnummer bedeutet, welche Änderungen unangekündigt kommen, was wir für API, SDKs, Plugin und MCP zusagen und wie Deprecation läuft.
Sie bauen auf BookDinePlay, damit es weiterläuft, während wir es verbessern. Diese Seite sagt genau, was wir zusagen, was sich ohne Vorwarnung ändern kann und wie Sie erfahren, was brechen wird. Jede Zusage hier wird entweder von einem Test in unserem Build oder vom Release-Prozess durchgesetzt; wo nicht, sagen wir es.
Was eine Versionsnummer bedeutet
BookDinePlay wird als eine nummerierte Einheit veröffentlicht, auf GitHub als vX.Y.Z getaggt. Dieselbe Nummer benennt alles, was zu Ihnen geliefert wird:
| Artefakt | Wo die Version steht |
|---|---|
| JavaScript-SDK | Der CDN-Pfad cdn.bookdineplay.com/sdk/<version>/bookdineplay.js |
| .NET-Pakete | BookDinePlay.Sdk und BookDinePlay.Shared auf nuget.org |
| WordPress-Plugin | bookdineplay-<version>.zip am GitHub-Release |
| API und MCP-Server | Mit dem Release ausgerollt; die API hat keine Version in der URL |
Eine Version mit einem - darin (zum Beispiel 0.24.0-rc.1) ist ein Pre-Release. Ein Pre-Release wird nur unter seinem exakten Versionspfad veröffentlicht: Er verschiebt nie den Major-Alias des CDN und steht nicht im Changelog.
Lesen Sie die Nummer als Major.Minor.Patch. Ein Patch korrigiert Verhalten, ohne zu ändern, was Sie aufrufen können. Ein Minor fügt Fähigkeiten hinzu und kann Verträge erweitern, wie unten erklärt. Ein Major ist das einzige Release, das etwas brechen darf, worauf Sie sich gemäß dieser Dokumentation gestützt haben.
Was die Zusage umfasst
Die Zusage umfasst, was diese Dokumentation beschreibt: die Routen der API-Referenz, die Problemtypen unter Fehler, die Optionen und Methoden des JavaScript-SDK, das .NET-SDK mit seinen Verträgen, die Shortcodes und Attribute des WordPress-Plugins sowie die Werkzeuge und Prompts des MCP-Servers. Alles, was hier nicht beschrieben ist – eine interne Route, die eigene Oberfläche der Konsole, ein Feld, das Sie in einer Antwort gefunden haben und das keine Seite nennt –, kann sich in jedem Release ändern.
Änderungen, die in jedem Release bei Ihnen ankommen können
Diese sind nicht brechend, und Ihre Integration muss sie vertragen:
- Neue Routen, neue optionale Anfragefelder und neue Antwortfelder. Ignorieren Sie Felder, die Sie nicht kennen.
- Neue Werte, wo ein Feld aus benannten Werten besteht: ein Reservierungs- oder Ticketstatus, ein Ressourcentyp, der
reasoneiner Ablehnung, ein Problemtyp, ein Tarifmerkmal. Behandeln Sie einen unbekannten Wert gelassen, statt zu scheitern. - Neue optionale Parameter an SDK-Methoden, neue SDK-Methoden, neue Widget-Optionen, neue Shortcode-Attribute, neue MCP-Werkzeuge und Prompts.
- Strengerer Schutz der Plattform: Ein Rate Limit ist das stehende Beispiel. Es wird vorab angekündigt, nie still eingeschaltet und auf die übliche Weise signalisiert (
429mitRetry-After) – siehe Rate Limits.
Eine Folge verdient eine klare Warnung. Das .NET-SDK liest benannte Werte streng: Ein Status, den es nicht kennt, lässt die Deserialisierung eine JsonException werfen, statt Ihnen einen überraschenden String zu geben. Das Release, das den Reservierungsstatus PaidButUnavailable einführte, ist das Beispiel, und es ist der Grund, warum das Changelog immer sagt, wenn ein Release einen solchen Wert hinzufügt und welche SDK-Version Sie dann brauchen. Halten Sie das SDK einigermaßen aktuell; das JavaScript-SDK reicht unbekannte Werte durch.
Was als brechend gilt
Eine Änderung ist brechend, wenn etwas, das wie dokumentiert funktionierte, nicht mehr funktioniert. Insbesondere: eine Route, ein Feld, eine SDK-Methode, eine Option oder ein Werkzeug entfernen oder umbenennen; den Typ eines Feldes ändern; die Bedeutung eines Status oder den Statuscode einer Ablehnung ändern; ein optionales Anfragefeld zur Pflicht machen; verengen, was ein in der Referenz dokumentiertes Limit erlaubt. Brechende Änderungen sind im Changelog mit Breaking markiert, selten, und ab Version 1.0 nur in einem neuen Major, nach der Deprecation-Frist unten.
Die veröffentlichten Verträge
BookDinePlay.Shared – die Anfrage- und Antworttypen, die SDK und API teilen – wird auf nuget.org veröffentlicht, daher ist die Änderung eines Typs die Änderung einer öffentlichen Schnittstelle mit Nutzern außerhalb dieses Repositorys. Was wir zusagen:
BookDinePlay.Sharedsagt Quellcode-Kompatibilität und JSON-Kompatibilität zu. Über ein Minor-Release hinweg ist ein Neukompilieren erforderlich. Eine neuere Assembly neben einen Konsumenten zu legen, der gegen die ältere kompiliert wurde, ohne neu zu kompilieren, wird ausdrücklich nicht unterstützt.
Wie das funktioniert, damit Sie es einplanen können. Verträge sind positionale Records, und sie wachsen durch angehängte, nachgestellte optionale Parameter. Das Anhängen ersetzt Konstruktor und Deconstruct des Records durch längere: Ihr Quellcode kompiliert weiter, weil die neuen Parameter optional sind, und eine alte Nutzlast lässt sich weiter deserialisieren, weil fehlende Member ihren Standardwert annehmen. Nur eine bereits kompilierte Assembly bemerkt es, als MissingMethodException zur Laufzeit – weshalb Sie beim Aktualisieren des Pakets neu kompilieren.
Darüber hinaus fügen wir nie einen Parameter in der Mitte ein, benennen nie einen Member um, ändern nie den Typ eines Members und machen nie einen bestehenden Member required. Eine Konstante wie eine maximale Länge wird in Ihre Assembly einkompiliert; sie zu verengen ändert für Sie also nichts, bis Sie neu bauen.
Das bleibt nicht dem guten Willen überlassen: Ein Test schreibt die gesamte öffentliche Oberfläche von BookDinePlay.Shared in einen freigegebenen Snapshot und lässt den Build bei jeder Änderung scheitern, mit dem Hinweis, ob es eine Erweiterung oder eine Inkompatibilität ist. Diesen Snapshot freizugeben ist die Review der öffentlichen API. Der Test spielt außerdem die Nutzlast jeder früheren Form jedes Records ab, um zu belegen, dass die Member, die es gab, unverändert zurückkommen. Nicht geprüft wird die Binärkompatibilität, weil sie nicht zugesagt ist.
Das JavaScript-SDK und das CDN
Das CDN liefert das SDK unter zwei Pfadformen mit unterschiedlichen Zusagen aus:
| Pfad | Inhalt | Cache |
|---|---|---|
sdk/<version>/bookdineplay.js |
Ein exaktes Release. Unveränderlich: Seine Bytes ändern sich nie | Ein Jahr |
sdk/v<major>/bookdineplay.js |
Das neueste Release dieser Major-Linie | Fünf Minuten |
Nehmen Sie den Alias, wenn Sie Korrekturen ohne Eingriff in Ihre Seite wollen. Ein neues Major bekommt einen eigenen Alias (sdk/v1/ nach sdk/v0/), und der alte Alias liefert weiter das letzte Release seiner Linie aus: Ein Alias springt nie auf ein neues Major, Ihre Seite wechselt die Major-Version also nur, wenn Sie den Pfad ändern. Legen Sie eine exakte Version mit ihrem Integritäts-Hash fest, wenn Ihre Richtlinie Byte-genaue Reproduzierbarkeit verlangt. Der Hash wird neben der Datei als sdk/<version>/sri.txt und am GitHub-Release veröffentlicht, nur je für eine exakte Version – nie für den Alias, dessen Inhalt sich absichtlich ändert. Details stehen im CDN.
Deprecation
Wenn etwas entfernt werden soll, erfahren Sie es zuerst und haben Zeit zum Umstieg:
- Angekündigt. Das Release, das etwas als veraltet kennzeichnet, listet es im Changelog unter Deprecated, nennt den Ersatz, und die Referenzseite des Elements sagt es ebenfalls. Im .NET-SDK ist der Member mit
[Obsolete]markiert, mit dem Ersatz in der Meldung. - Funktioniert weiter. Ein veraltetes Element funktioniert mindestens sechs Monate nach dem Release, das es angekündigt hat, unverändert weiter und wird nie in einem Release entfernt, das kein neues Major ist.
- Entfernt. Die Entfernung steht im Changelog des Major-Releases, das sie vornimmt, unter Breaking.
Die einzige Ausnahme ist ein Sicherheits- oder rechtlicher Grund, der kein Warten erlaubt. Dann wird die Änderung am selben Tag mit der Begründung angekündigt, und das Changelog sagt, dass die Frist verkürzt wurde.
Wie Sie davon erfahren
- Das Changelog listet jedes stabile Release, das neueste zuerst, mit allem, was eine Integration bemerken kann. Ein stabiles Release wird nicht ohne seinen Eintrag veröffentlicht: Der Release-Prozess lehnt ein stabiles Tag ab, das keinen Abschnitt für seine Version in beiden Sprachen hat.
- Jedes GitHub-Release verlinkt die Pakete und den Integritäts-Hash des SDK.
- Der Abschnitt Compatibility in der Readme des Pakets
BookDinePlay.Sharedwiederholt die obige Vertragszusage dort, wo ein Paketnutzer sie sieht.