Contract-first API-mocks

Waarom beginnen met een contract

Ik heb MockDeck gebouwd nadat ik teams zag verspillen aan weken wachten op een backend die nooit op tijd arriveerde. De eerste stap die ik zet bij elke nieuwe functie is het schrijven van een korte beschrijving van het eindpunt dat zowel frontend- als backend-ontwikkelaars kunnen bekijken. Die beschrijving wordt het contract. Wanneer het contract vaststaat, kan de frontend beginnen met coderen tegen een mock die exact hetzelfde gedrag vertoont als de echte service, terwijl het backend-team werkt aan de implementatie in parallel. Dit elimineert de periode van inactiviteit waarin ontwikkelaars naar een 404 of een placeholder kijken die alleen succescodes retourneert. Door het werk te verankeren in een concreet artefact, verkorten we de feedbacklus van dagen tot uren en voorkomen we de kostbare herwerking die optreedt wanneer aannamen over payloadvorm of foutafhandeling onjuist blijken te zijn.

Wanneer een contract vroeg bestaat, kunnen ontwerpers UI-componenten maken die de exacte gegevensvorm consumeren, kan QA testcases schrijven op basis van de gedefinieerde foutreacties en kan DevOps mock-servers configureren in staging-omgevingen zonder te wachten op de echte service. Het contract wordt een enkele bron van waarheid die miscommunicatie tussen disciplines vermindert. Het is ook belangrijk om te onthouden dat evenals kunnen helpen bij het verbeteren van de ontwikkelingsprocessen.

Het contract schrijven

Een contract moet elk waarneembaar gedrag van de endpoint vastleggen. Ik begin met het HTTP-pad en de methode, noteer dan eventueel een authenticatieschema (API-sleutel, bearer-token, wederzijdse TLS). Vervolgens maak ik een lijst van aanvraagparameters: query-strings, headers en body-velden, waarbij ik elk veld als verplicht of optioneel markeer. Voor elk veld voeg ik een type toe (tekenreeks, nummer, booleaans, array, object) en een formaat als dat nodig is (e-mail, datum-tijd, uuid). Ik definieer vervolgens het antwoord bij succes: statuscode, eventuele headers en de volledige vorm van de payload met typen en formaten. Ten slotte voeg ik foutgevallen toe die de frontend moet afhandelen: validatiefouten (400), niet gevonden (404), niet geautoriseerd (401), ratebeperking (429) en serverfouten (5xx). Voor elke fout voeg ik een voorbeeldbody toe die de vorm van de foutmelding laat zien.

Contractelement | Voorbeeldwaarde | Notities Pad | /v1/orders | Versie van de resource Methode | POST | Maakt een nieuwe order aan Auth | Bearer-token | Vereiste header Authorization Aanvraagbody - verplicht | customer_id (tekenreeks, uuid) | Moet bestaan in DB Aanvraagbody - optioneel | note (tekenreeks, max 500) | Vrije commentaar Succesantwoord | 201, {order_id, created_at} | Locatie-header met URL Validatiefout | 400, {errors: [{field: "customer_id", message: "moet uuid zijn"}]} | Helpt frontend om inline-waarschuwingen weer te geven Niet gevonden | 404, {error: "order niet gevonden"} | Treedt op bij GET /v1/orders/:id wanneer id onbekend is

Ik bewaar het contract in een platte-tekstbestand (YAML of JSON) dat naast de feature-branch staat. Dit maakt het gemakkelijk om wijzigingen te vergelijken tijdens codebeoordeling en om het artefact op te slaan in versiebeheer naast de broncode. Wanneer een contract wijzigt, toont de wijziging exact welk veld is toegevoegd, verwijderd of waarvan het type is gewijzigd, waardoor een gesprek tussen de eigenaren van de frontend en backend ontstaat voordat er code wordt geschreven.

Het genereren van de mock-specificatie

Zodra het contract is geschreven in een eenvoudig bestand of JSON-bestand, leest MockDeck het en produceert het drie artefacten: een OpenAPI 3-document, een Postman-verzameling en een raw routes-bestand (plat JSON met pad, methode en voorbeeldantwoorden). Het OpenAPI-uitvoer bevat de exacte schemas die u hebt gedefinieerd, plus automatisch gegenereerde voorbeelden die eruit zien als echte gegevens - denk aan namen die typische patronen volgen, nummers die binnen verwachte bereiken vallen en tekenreeksen die minimale en maximale lengtes bereiken. De Postman-verzameling kan rechtstreeks worden geïmporteerd in de API-client die u gebruikt voor handmatige tests, en het raw routes-bestand kan worden geserveerd door een lichtgewicht mock-server (zoals Mirage JS of json-server) met nul configuratie.

Het genereren van de mock is deterministisch: gegeven hetzelfde contractbestand krijgt u altijd dezelfde mock-uitvoer. Dit laat u toe om de gegenereerde artefacten te committen naar uw repository als u een statische mock wilt, of u kunt MockDeck uitvoeren als onderdeel van uw ontwikkelserver om de mock in het geheugen te houden. Omdat de mock afgeleid is van het contract, hoeft u nooit twee separate bronnen van waarheid te onderhouden; elke wijziging in het contract wordt automatisch doorgevoerd naar de mock wanneer u deze opnieuw genereert.

MockDeck voegt ook een paar handige functies toe uit de doos: het stelt de juiste CORS-kopteksten in voor lokale ontwikkeling, voegt een vertragingsschuiver toe zodat u netwerkvertraging kunt simuleren en logt elke aanvraag naar de console zodat u kunt verifiëren dat de frontend de verwachte eindpunten raakt met de correcte payload.

Mockservers integreren in de frontend-workflow

In mijn projecten voeg ik een startup-script toe dat de mockserver start voordat de frontend-devserver wordt gestart. Het script leest de contractmap, voert MockDeck uit om het routesbestand te produceren en start vervolgens een node-express-server die deze routes op http://localhost:3001 beschikbaar stelt. De frontend-proxy is zo geconfigureerd dat alle /api-verzoeken naar deze poort worden doorgestuurd, zodat de codebase een soepele API-laag ziet zonder enige wijzigingen in de broncode.

- Voeg een contracts-map toe aan de repository-root. - Maak voor elke endpoint een.yaml-bestand dat de eerder beschreven structuur volgt. - Voeg een start:mock-script toe in package.json dat mockdeck build./contracts --out./mock uitvoert en vervolgens node./mock/server.js start. - Configureer de frontend-devserver (bijv. Vite, CRA) om /api door te sturen naar http://localhost:3001. - Voer npm run start:mock uit in één terminal en npm run dev in een andere.

Wanneer een contract wijzigt, hoeft u alleen het mock-script opnieuw te starten; de frontend neemt het nieuwe gedrag direct over omdat de proxy naar de bijgewerkte mockserver doorstuurt. Deze korte cyclus moedigt ontwikkelaars aan om het contract als eerste artefact te behandelen wanneer een functie evolueert.

Ik schrijf ook een eenvoudige Jest-test die het gegenereerde OpenAPI-document importeert en controleert of de aanvraagvorm overeenkomt met de API-aanroepen van de component. Dit biedt een extra veiligheidsnet: als een ontwikkelaar per ongeluk de aanvraagpayload in de UI wijzigt, mislukt de test en wijst naar het contract als de bron van de waarheid.

Contracten versiebeheer en afwijkingen verwerken

Contracten evolueren net als code. Ik behandel elk contractbestand als een versie naast de feature-branch. Wanneer een breukverandering nodig is - zoals het hernoemen van een veld of het wijzigen van een vereiste vlag - maak ik een nieuwe versie van het contract (bijv. v2/order-create.yaml) en werk ik de OpenAPI-generator bij om een servers-blok te includeren dat naar het versiepad wijst. De mockserver serveert vervolgens beide versies tegelijk, waardoor de frontend de mogelijkheid heeft om in te schrijven op het nieuwe contract door de basis-URL te wijzigen.

Om afwijkingen te detecteren, voer ik een nachtelijke taak uit die de live backend OpenAPI-spec ( gegenereerd uit de daadwerkelijke code) vergelijkt met de contract- gegenereerde spec. Elke mismatch wordt gerapporteerd als een waarschuwing in ons CI-dashboard. Deze aanpak heeft gevallen opgevangen waarin een backend-ontwikkelaar een nieuw optioneel veld toevoegde zonder het contract bij te werken, wat validatiefouten in productie zou hebben veroorzaakt.

Wanneer een contract verouderd is, voeg ik een zonsondergangsdatum toe in een opmerking aan de top van het bestand en houd ik de mock actief voor twee weken na de datum om teams de tijd te geven om te migreren. Na die periode retourneert de mockserver een 410 Gone-respons met een korte verklaring, waardoor de levenscyclus van het contract expliciet wordt gemaakt.

Contract testing als veiligheidsnet

Contract testing verifieert dat de mock en de echte implementatie dezelfde taal spreken. Ik gebruik een tool zoals Pact of Dredd om het contract tegen zowel de mock-server als de staging-backend te laten draaien. Het testpakket verzendt elke aanvraag die in het contract is gedefinieerd, controleert de responsstatuscode, headers en bodemschema en registreert eventuele afwijkingen.

Het incorporeren van deze stap in de pull request-workflow betekent dat een wijziging in de backend die het contract verbreekt, de build faalt voordat deze de master bereikt.

Het contracttestpakket draait in minder dan twee seconden op een typische laptop, dus het voegt nauwelijks overhead toe aan de CI-pipeline, terwijl het een hoge mate van vertrouwen biedt dat de mock trouw blijft aan de overeengekomen specificatie, zoals beschreven in met behulp van tools als.

Wat dit niet is

Deze aanpak garandeert niet dat de backend op schema wordt geleverd. Een mock kan alleen gedrag simuleren; het kan de daadwerkelijke bedrijfslogica, database-interacties of externe service-aanroepen die de echte implementatie zal uitvoeren, niet vervangen.

Het is geen 100 % vervanging voor eind-tot-eindtesten. U moet nog steeds verifiëren dat het geïntegreerde systeem correct werkt met echte gegevens, prestatiekarakteristieken en foutcondities die alleen onder belasting kunnen verschijnen.

Het verwijdert niet de noodzaak voor duidelijke communicatie tussen teams. Het contract is een hulpmiddel om discussie te faciliteren, maar het vervangt geen reguliere synchronisaties, ontwerpreviews of gedeelde documentatie.

Ten slotte maakt het gebruik van contract-first-mocks uw product niet immuun voor specificatiefouten. Als het contract zelf ambigu of onvolledig is, zal de mock die lacunes trouw implementeren en zal de frontend tegen een gebrekkige veronderstelling worden gebouwd. Behandel het contract als een levend document dat evolueert met feedback van beide kanten.

Referenties

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Vaak gestelde vragen

Is dit een actieve mock-server?

Nee. MockDeck genereert de mock-API-specificatie — OpenAPI 3, Postman of raw routes. Het opzetten ervan is een aparte stap.

Kan het onze echte backend aanroepen?

Nee. Het proxyt of voert onze backend niet uit; de uitvoer is een specificatie en voorbeeldantwoorden.

Welke formaten produceert het?

OpenAPI 3, Postman-verzamelingen of raw routes.

Waarom zou je je druk maken over foutantwoorden in een mock?

Omdat dat is waar de frontend-code meestal breekt. Een mock die alleen 200s retourneert, verbergt de staten die je het meest moet afhandelen.

Hoe realistisch is de voorbeeldgegevens?

Het is gegenereerd om op echte payloads te lijken, wat voldoende is om formatting- en lege-staatfouten vroeg te detecteren. Het is geen productiegegevens.

Valideert het onze bestaande API tegen het contract?

Nee. Contracttesting en -validatie zijn aparte tooling.

Zijn er voorbeelden van hoe het kan worden gebruikt met ?

Ja, er zijn voorbeelden van hoe MockDeck kan worden gebruikt met in de documentatie van.

Referenties

- OpenAPI Specificatie - JSON Schema

Probeer het product: MockDeck

2026-09-20 · alleen primaire bronnen · geen gefabriceerde verkeersmetrieken · alleen beslissingsondersteuning

Gerelateerde artikelen

- MockDeck vs OpenAPI voorbeelden - Verken de volledige AI micro-SaaS onderwerpmatrix →