Versionierung

Die Partner API wird über die URL versioniert. Die aktuelle Version ist:

https://partner-api.performancehub.co/partner/v1/

Änderungsrichtlinie

Der Performance Hub ist bestrebt, nach Möglichkeit nur ergänzende, abwärtskompatible Änderungen vorzunehmen.

Beispiele für abwärtskompatible Änderungen:

Hinzufügen eines neuen optionalen Felds zu einer Anfrage.
Hinzufügen eines neuen Felds zu einer Antwort.
Hinzufügen eines neuen Endpunkts.
Hinzufügen eines neuen Enum-Werts, sofern von Clients erwartet wird, dass sie unbekannte Werte verarbeiten.
Verbesserung von Validierungsmeldungen, ohne den Vertrag für Statuscodes zu ändern.

access_time_windows und access_time_windows_revision sind ergänzende Anfragefelder für Mitglieder. Bestehende Clients, die sie weglassen, lassen den gespeicherten Access Time Windows-Snapshot unverändert. Diese Regel zum Weglassen erhält die Kompatibilität mit partiellen Upserts; das Weglassen ist nicht gleichbedeutend mit dem Senden eines leeren Arrays.

Beispiele für Breaking Changes:

Entfernen oder Umbenennen eines Felds.
Ändern des Typs eines Felds.
Ein optionales Anfragefeld zur Pflicht machen.
Entfernen eines Endpunkts.
Ändern der Bedeutung eines vorhandenen Statuscodes oder eines domänenspezifischen reason.

Einstellung von Funktionen

Wenn ein Breaking Change erforderlich ist, vermeidet der Performance Hub nach Möglichkeit, die bestehende Version direkt zu ändern. Stattdessen führen wir eine neue Version oder einen Migrationspfad ein und informieren die betroffenen Partner über die Änderung.

Hinweise auf eingestellte Funktionen können Folgendes umfassen:

Einen Eintrag im Änderungsprotokoll.
Direkte Kommunikation mit Partnern.
Hinweise in der Partner Console.
Migrationshinweise in der Dokumentation.

Empfehlungen für Clients

Entwickeln Sie Clients, die ergänzende Änderungen tolerieren:

Ignorieren Sie Antwortfelder, die Sie nicht verwenden.
Behandeln Sie unbekannte Enum-Werte als nicht unterstützt, statt abzustürzen.
Vermeiden Sie strikte Gleichheitsprüfungen von Antworten.
Protokollieren Sie nicht erkannte Werte, damit Sie Ihre Integration gezielt aktualisieren können.

Speichern Sie bei revisionierten Mitgliederpartitionen wie Access Time Windows die übermittelte Revision und die normalisierte Payload, bis das Ergebnis bekannt ist. Die Wiederverwendung einer Revision für geänderten Inhalt ist ein Konflikt, während die Wiederholung desselben Inhalts idempotent ist. Siehe Access Time Windows.

OpenAPI-Spezifikationen

Verwenden Sie die veröffentlichten OpenAPI-Spezifikationen, um Clients zu generieren, Anfragen zu validieren und Änderungen an der API-Struktur im Zeitverlauf nachzuverfolgen.

Siehe OpenAPI-Spezifikationen.