Beschrijving en handhaving onderscheiden
Leg een ondersteunde specificatieversie vast. Beschrijf parameters, inhoud, antwoorden en beveiligingseisen. Applicatie en gateway moeten deze eisen nog steeds zelf afdwingen.
| Element | Beschrijft | Aanvullende controle |
|---|---|---|
| Schema | Structuur en beperkingen | Werkelijke validatie en bedrijfsregels. |
| Gedocumenteerd antwoord | Verwachte status en inhoud | Overeenstemming van echte antwoorden. |
| Beveiligingseis | Aangegeven mechanisme en rechten | Werkelijke controle per handeling. |
| Voorbeeld | Eén illustratief geval | Samenhang, geen geheimen en grensgevallen. |
Vóór delen beoordelen
- Controleer verplichte velden, typen, bereiken, paginering, fouten en inhoudstypen. Gebruik fictieve schemaconforme voorbeelden zonder geheimen of klantgegevens.
- Vergelijk beschrijving met gecontroleerde verzoeken en antwoorden. Test ontbrekende aanmelding, onvoldoende rechten en scheiding tussen accounts.
- Controleer externe verwijzingen en verwerkende tools. Schoon publieke beschrijvingen op en bescherm private omgevingen en handelingen.
Documentatie onderhouden
Beoordeel verschillen en wijs een eigenaar aan. Gegenereerde clients en voorbeelden kunnen structureel kloppen maar bedrijfsregels missen. Interactieve consoles vereisen passende omgevingen, beperkte rechten en herkenbare toestandwijzigende handelingen.
Primaire bronnen
Vergelijk OpenAPI met de draaiende service.
Een nuttige OpenAPI-beschrijving bevat foutmeldingen, schema's en voorbeelden van problemen die clients daadwerkelijk tegenkomen. Wanneer de documentatie en de API van elkaar afwijken, kan een integratie een demo doorstaan en in productie mislukken.
- Vergelijk succesvolle en foutgevallen met de beschrijving.
- Documenteer optionele waarden, paginering en bewerkingslimieten.
- Test een representatieve client voordat het contract wordt gewijzigd.
Primaire bron: IETF RFC 9457 — Problem Details for HTTP APIs. Verwante methode: lees de praktische gids.
ZIP en TAR: uitpakken binnen pad- en resourcelimieten
Controleer paden, links en uitgepakte gegevens voordat bestanden worden vrijgegeven.
- Pak uit in een nieuwe niet-openbare map met minimale rechten. Weiger absolute paden, maptraversal, onnodige links en speciale bestanden. Controleer opgeloste doelen en botsingen volgens het doelsysteem, inclusief hoofdletters. Een tekstprefix bewijst geen insluiting.
- Stel per-bestand- en totaallimieten voor geschreven bytes, items, diepte, tijd en procesresources. Vertrouw niet alleen op gecomprimeerde of opgegeven grootte. Weiger onnodige geneste archieven; gebruik anders een gezamenlijk budget. Houd bibliotheek en filters actueel.
- Test ../, absoluut pad, link, duplicaat en budgetoverschrijding. Een onderbreking laat de batch ongepubliceerd en vervangt geen bestaande bestanden. Controleer typen en inhoud vóór vrijgave; verifieer het doel bij opruimen.
Herhaalbare acceptatiecasus
Fictief voorbeeld: deze gegevens beschrijven geen klant of waargenomen resultaat.
Casusgegevens bekijken
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Verwachte beslissing
Fictief voorbeeld: 2 MB gecomprimeerd levert 600 MB bij een budget van 100 MB. Stop bij overschrijding van geschreven bytes en publiceer niets, ook als eerste bestanden geldig lijken.
Python — tarfile extraction filters and further verification
Garandeert een klein archief of filter veiligheid?
Nee. Kleine archieven kunnen sterk groeien. Voeg resourcelimieten, padregels en controle van uitvoerbestanden toe.
Primaire bron: Python — tarfile extraction filters and further verification. Verwante methode: lees de praktische gids.
API-fouten: typen, statussen en bewijs
De uitgebreide toelichtingen zijn in deze editie beschikbaar in het Engels.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5