Stel dat een bestelwebsite een nieuwe order naar een operationeel systeem stuurt. Het systeem slaat de order op, maar de bevestiging bereikt de website niet. Moet de website het opnieuw proberen? Kan dat een tweede order opleveren? Deze voorbeeldsituatie laat zien waarom een API-contract belangrijk is voor de bedrijfsvoering. Het beschrijft het verwachte gedrag aan beide kanten, inclusief situaties die in een geslaagde demonstratie misschien nooit zichtbaar worden.
Op deze pagina
Begin met het bedrijfsproces en de verantwoordelijkheid voor data
Breng één interactie in kaart van de gebruikersactie tot het bevestigde resultaat. Bepaal in het ordervoorbeeld wie de orderreferentie aanmaakt, welk systeem beslist of de order wordt geaccepteerd en waar de klant de status bekijkt. Maak onderscheid tussen een ontvangen verzoek en een geaccepteerde order: dat kunnen verschillende gebeurtenissen zijn. Beslis ook welk systeem elk gegeven mag wijzigen. Als beide systemen een afleveradres kunnen aanpassen, heeft het contract een regel nodig voor updates, in plaats van aan te nemen dat het nieuwste scherm de gezaghebbende waarde toont.
- Benoem de verantwoordelijke voor order-, klant- en statusinformatie.
- Leg vast welk resultaat de gebruiker direct moet zien.
- Bepaal welke latere updates het ontvangende systeem moet versturen.
Maak velddefinities concreet
Documenteer per bericht de verplichte informatie, toegestane waarden en de betekenis van ontbrekende informatie. Een prijs vereist een valuta en een duidelijke interpretatie; een tijdstempel een afgesproken tijdzoneconventie. Gebruik één realistische voorbeeldorder om deze regels te bespreken. Vraag of ‘geannuleerd’ de hele order of één artikel beschrijft en of een leeg adres onbekend of bewust verwijderd betekent. Beschrijf welke records iedere aanroeper mag lezen of wijzigen. Deze beslissingen beïnvloeden zowel de specificatie als de gebruikerservaring; alleen gelijke veldnamen bieden geen antwoord.
Specificeer herhaalde verzoeken en bruikbare fouten
Voor de voorbeeldorder kan een voorgestelde regel luiden: binnen een afgesproken bewaartermijn levert opnieuw versturen van dezelfde verzoek-ID met identieke ordergegevens de bestaande orderreferentie op. Hergebruik van die ID met andere gegevens veroorzaakt een conflict dat de aanroeper moet oplossen. Definieer het toepassingsbereik en de bewaartermijn van de ID expliciet. Maak daarna onderscheid tussen fouten die correctie vereisen en tijdelijke storingen. Een time-out alleen bewijst niet of de order is opgeslagen. De aanroeper heeft daarom een manier nodig om het resultaat te controleren voordat de volgende stap wordt bepaald.
- Ontbrekend afleveradres: geef uitleg op veldniveau terug; corrigeer het verzoek voordat het opnieuw wordt verstuurd.
- Onzeker resultaat: zoek de verzoek-ID op en stem af op de geregistreerde toestand.
- Tijdelijke servicestoring: volg het afgesproken herhaalbeleid; maak niet voor iedere poging een nieuwe orderidentiteit aan.
Spreek af hoe het contract wordt getest en gewijzigd
Laat beide teams een geslaagde order, een herhaald verzoek, een ongeldig adres en een onderbroken bevestiging doorlopen. Controleer of ze in elk geval hetzelfde resultaat verwachten. Bewaar deze voorbeelden bij de specificatie en gebruik ze wanneer de integratie verandert. Benoem wie wijzigingen goedkeurt, aangesloten teams informeert en incidenten onderzoekt. Een overdracht moet uitleggen hoe support een verzoek kan volgen zonder onnodige klantgegevens bloot te leggen, en hoe een niet-compatibele wijziging wordt ingevoerd bij bestaande API-gebruikers.