Praktische gidsen

Documenteer en test een API uit de use-cases

Een handige API laat een ander team begrijpen wat het kan vragen en wat het zal ontvangen. Het contract moet testbaar zijn, geversiet en consistent zijn met de operationele service.

Zie de methode

Illustratie — Documenteer en test een API uit de use-cases
AI-gegenereerde illustratie

Kies taken voor adressen

JavaScript: numeriek 9007199254740993 rondt af; de string behoudt cijfers.
Illustratie · JSON.parse-voorbeeld: Number rondt het token af, String bewaart cijfers. Spreek tekstrepresentatie vooraf af.

Gebruik een lijst van toepassingen zoals het vinden van een product, het lezen van beschikbaarheid, het bijwerken van een record of het bijhouden van tracking. Definieer geautoriseerde mensen en systemen voor elke operatie. Een openbare lees-API en een administratieve API hebben verschillende toegangsvereisten.

Bereid een verzoek en antwoordvoorbeeld voor elke essentiële taak met behulp van synthetische waarden en uitgelegde velden. Onderscheid stabiele identificaties, labels, eenheden en datums. Definieer ontbrekende gegevens in plaats van aannemelijke waarden te vervangen door onbekende informatie.

Leg grote identifiers expliciet vast in JSON. Bij JavaScript Number met binary64 liggen gehele getallen van −9007199254740991 tot 9007199254740991 binnen RFC 8259’s exacte interoperabiliteitsbereik. 9007199254740992 is wel weergeefbaar maar geen veilig geheel getal: het naburige token 9007199254740993 wordt bij gewone JavaScript-JSON-decodering 9007199254740992.

Als JSON-string behoudt dezelfde identifier zijn cijfers. Stem dit af tussen producent, schema en consument; tekst maken van een al afgeronde Number herstelt het origineel niet. Andere bibliotheken kunnen meer precisie behouden: test ondersteunde clients. Geldige JSON bewijst geen waardetrouw en het identificatortype mag niet stilzwijgend wisselen.

Schuif de tabel horizontaal om alle kolommen te lezen. Zet met het toetsenbord de focus op de tabel en gebruik de pijltjestoetsen.

JavaScript-JSON-decodering: precisie en type
JSON-voorbeeldtokenGetoonde JavaScript-waardeBetekenis
90071992547409919007199254740991Veilig geheel getal in dit voorbeeld
90071992547409929007199254740992Exact maar buiten het veilige bereik
90071992547409939007199254740992Afgerond: laatste oorspronkelijke cijfer verloren
"9007199254740993""9007199254740993"Exacte string; afgesproken teksttype

een expliciet contract beschrijven

OpenAPI biedt een taalonafhankelijk beschrijvingsformaat voor HTTP API's, met bewerkingen, parameters, antwoorden en modellen. Kies een versie die door uw tools wordt ondersteund en bewaar het document bij het project; De nieuwste versie is niet automatisch de juiste pasvorm voor elke toolchain.

Documentgebruikslimieten, paginering, filters, bestellingen, fouten en lege reacties. Behandel COR's niet als bewijs van autorisatie. Bekijk de bediening en toegangscontroles op objectniveau met het technische team.

Beschrijf voor een fictieve API voor aanvraagverwerking de vier antwoorden hieronder apart. In deze afspraken levert 201 een aangemaakte bron met de Location-header; 202 levert een volgnummer omdat de verwerking nog niet klaar is. Vertaal niet ieder 2xx-antwoord naar ‘bewerking voltooid’. De client moet de status, headers en het voor die bewerking beschreven model lezen.

Een 204-antwoord heeft geen inhoud om als JSON te decoderen. In dit voorbeeld krijgt een syntactisch juiste instructie die een bedrijfsregel schendt 422 met een gestructureerd probleem in application/problem+json. Als het lid status wordt meegestuurd, moet de producent het laten overeenkomen met de werkelijke HTTP-status; vertaalde tekst in detail mag geen beslissleutel voor software worden. Documenteer vaste probleemidentificaties en de verwachte correctie.

Schuif de tabel horizontaal om alle kolommen te lezen. Zet met het toetsenbord de focus op de tabel en gebruik de pijltjestoetsen.

Vier antwoorden van een fictieve API en hun gevolgen voor de client
Gepland antwoordVastgesteld feitControle door de afnemer
201 CreatedBron aangemaaktControleer afgesproken Location en aangemaakte identificatie
202 AcceptedVerwerking geaccepteerd, nog niet afgerondBewaar de volgverwijzing; wacht op het eindresultaat
204 No ContentActie geslaagd, zonder antwoordinhoudDecodeer geen lege inhoud als JSON
422 Unprocessable ContentInstructie begrepen maar niet verwerkbaar volgens de regelLees het gestructureerde probleem en bied een passende correctie
  • RFC 9110 : HTTP Semantics

    RFC 9110, geraadpleegd op 22 oktober 2026: betekenis van statussen. De antwoorden en verplichte velden zijn fictieve afspraken.

  • RFC 9457 : Problem Details

    RFC 9457, geraadpleegd op 22 oktober 2026: probleemformaat en de rol van het lid status.

Voorkomen dat een wijziging die van een andere redacteur overschrijft

  1. Twee keer r7 lezen
  2. Eerste schrijfactie: r8
  3. Oude schrijfactie: 412
  4. Vergelijken vóór hervatten

Fictief geval: twee redacteuren openen DEMO-17 met de sterke ETag "r7". De eerste bewaart een correctie; de huidige representatie wordt "r8". De tweede werkt nog met "r7". Voorwaardelijk schrijven kan dit verschil vóór vervanging van de gepubliceerde versie ontdekken.

Bij een API die dit contract ondersteunt, stuurt de client If-Match met de ontvangen sterke validator. De server vergelijkt de versie vóór het schrijven; dit voorbeeld voorziet 412 als die is veranderd. W/"r7" is zwak en voldoet niet aan sterke vergelijking. If-Match: * controleert of een huidige representatie bestaat, niet of deze sinds het lezen gelijk bleef.

Bewaar het concept van de tweede redacteur, lees de huidige versie en toon verschillen voordat opnieuw wordt beslist. De validator automatisch door "r8" vervangen en het oude concept opnieuw sturen zou de bescherming omzeilen. Controle en schrijven moeten ondeelbaar zijn in de opslag; twee gelijktijdige verzoeken met dezelfde validator mogen niet beide dezelfde versie overschrijven.

Deze controle vervangt geen authenticatie, rechten op het record of veldvalidatie. Ze garandeert evenmin eenmalige uitvoering van een externe aanroep. Test deze eigenschappen apart en beschrijf ontbrekende voorwaarden; 428 kan een voorwaardelijk verzoek vereisen.

Schuif de tabel horizontaal om alle kolommen te lezen. Zet met het toetsenbord de focus op de tabel en gebruik de pijltjestoetsen.

Twee redacteuren, één huidige versie: fictieve testreeks
StapVersie en verzoekVerwacht resultaat van dit contract
Beiden lezenETag: "r7"Ieder bewaart de validator bij het concept.
Eerste keer bewarenIf-Match: "r7" → versie "r8"De eerste correctie blijft behouden.
Verouderd tweede verzoekIf-Match: "r7"; huidige versie "r8"412; de bewaarde correctie niet vervangen.
Bewust vergelijken"r8" lezen, vergelijken en beslissenConcept bewaren en rechten vóór opnieuw schrijven controleren.

Grenzen en machtigingen testen

Probeer een bestaand object, een ontbrekend object, een ongeldige parameter en een lijst langer dan één pagina. Controleer de volgende pagina op verliezen of herhalingen binnen het gekozen updatemodel. Vermeld beperkingen die de API niet kan garanderen.

Gebruik testaccounts met verschillende machtigingen. Poging leest en wijzigt buiten het toegestane bereik met behulp van synthetische gegevens. Noteer verwachte statussen en nuttige berichten zonder interne sporen of configuratiegeheimen vrij te geven.

Plan verandering en ondersteuning

een toegevoegd veld onderscheiden van een verwijderd veld of een gewijzigde betekenis. Identificeer consumenten vóór een onverenigbare verandering. Leg de overgangsperiode uit en hoe u integraties kunt detecteren met behulp van het eerdere contract.

Lever een uitvoerbaar voorbeeld voor een testomgeving, een testmatrix en een technisch contact. Breng waargenomen fouten in verband met gedocumenteerde voorbeelden na release. Documentatie beperkt tot de ideale case laat integrators zonder begeleiding voor weigeringen en onderbrekingen.

Primaire documentatie: OpenAPI-initiatief : Specificatie.

Referentiedocumenten

Inhoud bijgewerkt

Gedocumenteerde referenties voor dit onderwerp

Gedocumenteerde referenties voor dit onderwerp
ReferentieWaarde of syntaxisToepassingsgebied
RFC 8259 · JSON
application/json · UTF-8Standaard-JSON staat geen commentaar of afsluitende komma toe; tekenreeksen gebruiken dubbele aanhalingstekens.
RFC 3339 · Date-time
2026-10-22T09:00:00+02:00Het expliciete tijdsverschil koppelt lokale tijd aan UTC; dit voorbeeld is geen afspraak.
HTTP · If-Match
If-Match: "r7" → 412If-Match vergelijkt een sterke validator vóór een schrijfactie. In dit contract krijgt een verouderde versie 412; bewaar het concept om wijzigingen te vergelijken.
HTTP · 428
428 · Precondition RequiredMet 428 kan een server een voorwaardelijk verzoek vereisen. Leg het gebruik vast in het contract; de status biedt zelf geen vergrendeling.

De datums geven aan wanneer de bronnen zijn geraadpleegd. Deze gegevens vormen geen site-audit of algemene conformiteitsverklaring.

Scheid HTTP-status, JSON en bedrijfsresultaat

Kies een fictieve uitwisseling en probeer die lokaal te lezen. HTTP-succes, leesbaar JSON en een voltooide bewerking vragen aparte controles.

De fragmenten zijn onvolledig en gebruiken demo-adressen. De proef maakt een Response in het geheugen: geen servercontact en geen simulatie van netwerk, cache of bedrijfsverwerking.

200Een nieuwe volledige representatie
Betekenis
In dit fragment beantwoordt de server een voorwaardelijke GET met JSON-inhoud en validator demo-v2.
Te controleren
Vergelijk If-None-Match, ETag en de revisie in de inhoud. De lokale proef leest het JSON van dit voorbeeld.
Let op
Status 200 garandeert geen geldig JSON of juiste bedrijfsgegevens. Succesvol ontleden hier valideert uw eigen gegevensschema niet.
Fragment van een fictieve uitwisseling
GET /demo/catalogue
If-None-Match: "demo-v1"

HTTP/1.1 200 OK
ETag: "demo-v2"
Content-Type: application/json

{"revision":"demo-v2"}

202Geaccepteerd, verwerking nog niet klaar
Betekenis
202 meldt acceptatie voor verwerking, geen voltooiing. De fictieve inhoud meldt queued.
Te controleren
Bewaar DEMO-42 en volg de toestand volgens het API-contract, inclusief rechten en herhaallimieten.
Let op
Response.ok is true. Die waarde en leesbaar JSON bewijzen geen voltooiing. Velden en volgadres zijn fictieve afspraken.
Fragment van een fictieve uitwisseling
POST /demo/jobs

HTTP/1.1 202 Accepted
Location: /demo/jobs/DEMO-42
Content-Type: application/json

{"job":"DEMO-42","status":"queued"}

204Verzoek uitgevoerd, geen antwoordinhoud
Betekenis
204 geeft aan dat de server het verzoek uitvoerde zonder antwoordinhoud. Dit fragment bevat geen JSON.
Te controleren
Behandel de ontbrekende inhoud volgens het contract. Bepaal wat het ontvangende eindpunt precies bevestigt vóór u een resultaat meldt.
Let op
Lege inhoud als JSON lezen mislukt terwijl Response.ok true is. Bij een webhook kan alleen ontvangst bevestigd zijn; latere bedrijfsacties vragen nog controle.
Fragment van een fictieve uitwisseling
POST /demo/events

HTTP/1.1 204 No Content

304Kopie hervalideerd, geen nieuwe inhoud
Betekenis
304 beantwoordt een voorwaardelijk verzoek: de opgeslagen representatie kan opnieuw worden gebruikt. Er komt geen nieuwe inhoud.
Te controleren
Vergelijk de verzonden validator met de aanwezige kopie demo-v2. De uitleg hangt ook van die opgeslagen kopie af.
Let op
De proef maakt een losse Response 304, geen HTTP-cache. Bij echte fetch kan de browser de opgeslagen respons leveren; netwerkstatus en scriptstatus kunnen verschillen.
Fragment van een fictieve uitwisseling
GET /demo/catalogue
If-None-Match: "demo-v2"

HTTP/1.1 304 Not Modified
ETag: "demo-v2"

Technische bronnen : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

Functionele validatiematrix om zich aan het project aan te passen

Deze voorgestelde controles gebruiken fictieve gevallen. Bepaal welk gedrag er met het team wordt verwacht, noteer het resultaat en wijs onopgeloste discrepanties toe voor publicatie.

Schuif de tabel horizontaal om alle kolommen te lezen. Zet met het toetsenbord de focus op de tabel en gebruik de pijltjestoetsen.

Testgevallen, verwachte resultaten en nuttig bewijs
GevalVerwacht resultaatBewijs om te houden
Huidige en afwezige middelenElke uitkomst komt overeen met het gedocumenteerde status- en responsmodel.Verzoek, respons en bijbehorende contractvoorbeeld vastgelegd uit de testomgeving.
Parameter buiten bereikDe weigering is begrijpelijk en legt geen interne stacktracering bloot.openbaar bericht en resultaat bewaard in de acceptatiematrix.
Twee machtigingsniveausEen verboden hulpbron blijft zelfs met een bekende identifier ontoegankelijk.Vergeleek resultaten met behulp van twee synthetische accounts met expliciet verschillende toestemmingen.
Paginering en gewijzigd filterTokenafhandeling en herstartgedrag van de reis zijn gedefinieerd.Bestelling, geretourneerde identificatiegegevens en regels die van toepassing zijn wanneer het filter verandert.

Veel gestelde vragen

Is gegenereerde documentatie voldoende om een API te testen?

Het helpt bij het lezen van een contract, maar machtigingen, ontbrekende gegevens, fouten, lijsten en wijzigingen vereisen nog steeds testen. Vergelijk voorbeelden met feitelijke test-omgevingsreacties.

Vervangt CORS toegangsrechten?

Nee. Cross-origin-regels vervangen de bedienings- en objectmachtigingen van de service niet. Beschrijf die machtigingen en test handhaving aan de serverzijde met testaccounts.

Verwante onderwerpen