Geschatte leestijd : 8 min · Gepubliceerd
Kies taken voor adressen
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.
| JSON-voorbeeldtoken | Getoonde JavaScript-waarde | Betekenis |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Veilig geheel getal in dit voorbeeld |
| 9007199254740992 | 9007199254740992 | Exact maar buiten het veilige bereik |
| 9007199254740993 | 9007199254740992 | Afgerond: 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.
| Gepland antwoord | Vastgesteld feit | Controle door de afnemer |
|---|---|---|
| 201 Created | Bron aangemaakt | Controleer afgesproken Location en aangemaakte identificatie |
| 202 Accepted | Verwerking geaccepteerd, nog niet afgerond | Bewaar de volgverwijzing; wacht op het eindresultaat |
| 204 No Content | Actie geslaagd, zonder antwoordinhoud | Decodeer geen lege inhoud als JSON |
| 422 Unprocessable Content | Instructie begrepen maar niet verwerkbaar volgens de regel | Lees 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
- Twee keer r7 lezen
- Eerste schrijfactie: r8
- Oude schrijfactie: 412
- 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.
| Stap | Versie en verzoek | Verwacht resultaat van dit contract |
|---|---|---|
| Beiden lezen | ETag: "r7" | Ieder bewaart de validator bij het concept. |
| Eerste keer bewaren | If-Match: "r7" → versie "r8" | De eerste correctie blijft behouden. |
| Verouderd tweede verzoek | If-Match: "r7"; huidige versie "r8" | 412; de bewaarde correctie niet vervangen. |
| Bewust vergelijken | "r8" lezen, vergelijken en beslissen | Concept bewaren en rechten vóór opnieuw schrijven controleren. |
- IETF · RFC 9110 § 13.1.1
IETF : Voorwaardelijk schrijven en voorwaarden
- IETF · RFC 6585 § 3
428 · Precondition Required
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
- OpenAPI-initiatief : Specificatie · Bron geraadpleegd
- IETF : RFC 8259: JSON numbers · Bron geraadpleegd
- TC39 : Number.isSafeInteger · Bron geraadpleegd
Inhoud bijgewerkt
Gedocumenteerde referenties voor dit onderwerp
| Referentie | Waarde of syntaxis | Toepassingsgebied |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | Standaard-JSON staat geen commentaar of afsluitende komma toe; tekenreeksen gebruiken dubbele aanhalingstekens. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Het expliciete tijdsverschil koppelt lokale tijd aan UTC; dit voorbeeld is geen afspraak. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-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 Required | Met 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.
