Stel dat een klant in een portaal een supportverzoek indient. Het scherm blijft hangen en meldt een timeout. De klant klikt opnieuw op ‘Versturen’. Krijgt support nu één ticket of twee? Voor het portalteam is dat een ontwerpvraag. Zodra ook een mobiele app of een partner hetzelfde proces gebruikt, wordt het een afspraak waar meerdere teams op moeten kunnen bouwen.
Leg vast waarop een andere client mag rekenen
Bij API-first maak je die afspraken vroeg, zodat de teams die de API bouwen en gebruiken dezelfde verwachtingen hebben. Voor het portaal begint dat bij een concrete operatie zoals POST /support-tickets. Welke velden zijn verplicht? Wie mag namens een organisatie een ticket openen? Welk ticketnummer krijgt de client terug?
Met OpenAPI kun je een HTTP-interface beschrijven, inclusief invoer, responses en het vereiste beveiligingsmechanisme. Leg de autorisatieregel ook vast in de implementatie en test haar afzonderlijk. Een geldig token vertelt de server bijvoorbeeld nog niet of de gebruiker een ticket mag aanmaken voor de organisatie die in het verzoek staat.
Het contract verdient extra aandacht zodra clients op verschillende momenten releasen. Als een bestaande app ticketId leest, kan het hernoemen van dat veld naar id een oudere app breken. Laat een compatibiliteitscheck vóór de backendrelease het oude responseformaat controleren. Wijs ook iemand aan die beslist wanneer een veld weg mag en hoe afnemers vooraf bericht krijgen. GitHub gebruikt voor zulke wijzigingen gedateerde REST API-versies. Voor het portaal kan een overgangsperiode waarin beide velden beschikbaar zijn voldoende zijn.
Beslis waar de netwerkgrens nodig is
In een servergerenderd portaal dat één team als één toepassing uitrolt, kan de formulierhandler direct een interne ticketmodule aanroepen. Je kunt de invoer, rechten en foutgevallen ook aan die interne interface expliciet maken. Een extra HTTP-aanroep tussen twee onderdelen van dezelfde toepassing vraagt om eigen afspraken over timeouts en foutafhandeling. Die grens verdient pas een plek als ze een concreet probleem oplost.
Komt er een zelfstandige mobiele app bij, dan kan dezelfde toepassing een HTTP-endpoint aanbieden dat de ticketmodule aanroept. De app krijgt een eigen interface en releasecyclus. De backend kan als één toepassing blijven draaien. Pas als er een aparte reden is om de ticketfunctie zelfstandig uit te rollen of te beheren, komt een afzonderlijke service in beeld.
Ontwerp de tweede klik
Na een timeout kan het eerste ticket al zijn opgeslagen. Als de client automatisch mag herhalen, moet de server een herhaling kunnen herkennen. Spreek bijvoorbeeld af dat de client bij dezelfde poging dezelfde idempotency key meestuurt en dat de server na een afgeronde poging het oorspronkelijke ticketnummer teruggeeft. Leg ook vast wat er gebeurt als dezelfde sleutel met andere invoer binnenkomt of als twee verzoeken tegelijk arriveren.
Stripe API v1 geeft een gedocumenteerd voorbeeld. Stripe vergelijkt de invoer bij hergebruik van de sleutel. Sleutels kunnen na minstens 24 uur worden verwijderd, waarna hergebruik tot een nieuwe aanvraag kan leiden. Kies voor het portaal zelf een bewaartermijn die past bij de periode waarin clients mogen herhalen.
Neem de timeout mee in de eerste acceptatietest voor de API. Laat het ticket opslaan, onderbreek de response en stuur hetzelfde verzoek opnieuw. Controleer vervolgens welk ticketnummer de client terugkrijgt en hoeveel tickets er zijn opgeslagen. Dat is de afspraak die straks ook moet gelden wanneer de mobiele app en het portaal op verschillende momenten worden bijgewerkt.
Bronnen
Neem contact met ons op
Vertel ons waarmee we kunnen helpen; we reageren binnen twee werkdagen.
