Versiebeheer

De versie van de Partner API staat in de URL. De huidige versie is:

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

Wijzigingsbeleid

Performance Hub streeft ernaar om waar mogelijk aanvullende, achterwaarts compatibele wijzigingen door te voeren.

Voorbeelden van achterwaarts compatibele wijzigingen:

Een nieuw optioneel veld aan een verzoek toevoegen.
Een nieuw veld aan een response toevoegen.
Een nieuw endpoint toevoegen.
Een nieuwe enumwaarde toevoegen waar van clients wordt verwacht dat ze onbekende waarden afhandelen.
Validatieberichten verbeteren zonder het contract voor statuscodes te wijzigen.

access_time_windows en access_time_windows_revision zijn aanvullende velden in Member-verzoeken. Bestaande clients die ze weglaten, laten de opgeslagen momentopname van Access Time Windows ongewijzigd. Deze regel voor weglaten behoudt de compatibiliteit met gedeeltelijke upserts; weglaten is niet hetzelfde als een lege array sturen.

Voorbeelden van wijzigingen die compatibiliteit verbreken:

Een veld verwijderen of hernoemen.
Het type van een veld wijzigen.
Een optioneel veld in een verzoek verplicht maken.
Een endpoint verwijderen.
De betekenis van een bestaande statuscode of domeinspecifieke reason wijzigen.

Uitfasering

Wanneer een wijziging nodig is die compatibiliteit verbreekt, vermijdt Performance Hub waar mogelijk om de bestaande versie ter plekke te wijzigen. In plaats daarvan introduceren we een nieuwe versie of een migratiepad en communiceren we de wijziging aan de betrokken partners.

Meldingen over uitfasering kunnen bestaan uit:

Een vermelding in het wijzigingslogboek.
Directe communicatie met partners.
Opmerkingen in de Partner Console.
Migratierichtlijnen in de documentatie.

Aanbevelingen voor clients

Bouw clients die bestand zijn tegen aanvullende wijzigingen:

Negeer responsevelden die je niet gebruikt.
Behandel onbekende enumwaarden als niet-ondersteund in plaats van te crashen.
Vermijd strikte gelijkheidscontroles op responses.
Log onbekende waarden, zodat je je integratie bewust kunt bijwerken.

Bewaar voor Member-partities met revisies, zoals Access Time Windows, de ingediende revisie en de genormaliseerde payload totdat de uitkomst bekend is. Een revisie hergebruiken voor gewijzigde inhoud is een conflict, terwijl het herhalen van dezelfde inhoud idempotent is. Zie Access Time Windows.

OpenAPI-specificaties

Gebruik de gepubliceerde OpenAPI-specificaties om clients te genereren, verzoeken te valideren en wijzigingen in de structuur van de API in de loop van de tijd te volgen.

Zie OpenAPI-specificaties.