Bronnen · 33
Ontwikkel API-contracten zonder klanten te verliezen.
Beschrijf verzoeken, reacties en fouten; test versies en zorg ervoor dat webhooks veilig opnieuw kunnen worden afgespeeld.
Bijgewerkt · 2 min
Wat deze handleiding helpt bereiken
- Schrijf het contract
- Verduidelijk fouten
- Test compatibiliteit
- Plan de uitfasering
Snelle controle
- Welke clients gebruiken elke bewerking?
- Hebben fouten stabiele typen en coherente statussen?
- Kan een oude client de wijziging tolereren?
- Kunnen herhaalpogingen een actie dupliceren?
- Hoe wordt de uitfasering aangekondigd en geverifieerd?
Stapsgewijze methode
- 1
Inventariseer gebruikers
Maak een lijst van bewerkingen, clients, gebruikswijzen, versies en eigenaren. Scheid waargenomen gebruik van aannames voordat een veld wordt gewijzigd.
Resultaat: contractafhankelijkheidskaart.
- 2
Beschrijf verzoeken en antwoorden
Onderhoud een OpenAPI-beschrijving met schema's, realistische voorbeelden, succes- en foutreacties. Controleer deze aan de hand van de draaiende service.
Resultaat: versiebeheerd contract en conformiteitstests.
- 3
Stabiliseer fouten
Gebruik HTTP-statussen volgens hun semantiek en, waar nuttig, een gedocumenteerd probleemtype volgens RFC 9457. Geef geen geheimen in detail weer.
Resultaat: geteste foutencatalogus.
- 4
Classificeer de wijziging
Inspecteer vereiste velden, typen, waarden, gedrag, time-outs en paginering. Test oude clients tegen de nieuwe versie met representatieve gevallen.
Resultaat: compatibiliteitsmatrix en versiebeslissing.
- 5
Maak meldingen robuust
Plan voor webhooks authenticatie, ongeordende levering, duplicaten en herhaalpogingen. Maak de verwerking idempotent waar herhaling mogelijk is.
Resultaat: scenario voor herhaling en bevestiging.
- 6
Release met een exitplan
Publiceer migratienotities, coëxistentieperiode en contactpersonen. Meet het gebruik van de oude versie en trek deze pas uit na controle van de getroffen gebruikers.
Resultaat: migratieplan en bewijs van uittreding.
Managementindicatoren
| Indicator | Wat het meet | Eerste actie |
|---|---|---|
| Contract | Beschrijving van bewerkingen en overeenkomend servicegedrag | Afwijking corrigeren |
| Compatibiliteit | Representatieve clients getest vóór wijziging | Ontbrekende gevallen toevoegen |
| Fouten | Gedocumenteerde typen zonder gevoelige gegevens | Berichten en schema's herzien |
| Migratie | Gebruik van oude versie met een eigenaar | Overige clients ondersteunen |
Veelvoorkomende fouten
- Ervan uitgaande dat alleen een versienummer de compatibiliteit behoudt
- Slechts 200 reacties documenteren
- Een interne trace of geheim retourneren bij een fout
- Ervan uitgaande dat webhooks één keer en in de juiste volgorde aankomen
Veelgestelde vragen
Vervangt OpenAPI testen?
Nee. Vergelijk de beschrijving met echte reacties en de behoeften van de gebruiker.
Vereist elke wijziging een nieuwe versie?
Nee. Beslis op basis van de impact op de client en het contractgedrag; Incompatibele wijzigingen vereisen een expliciet plan.
Waarom typefouten?
Ze bieden klanten een stabiele manier om problemen te onderscheiden en een actie te kiezen.
Officiële referenties
Referenties ondersteunen de methode. Pas controles aan uw context aan; ze zijn geen certificering. Originele referentietitels en brondocumenten kunnen in een andere taal zijn.
