Separate description, validation and authorization
Pin a specification version your tools support. Describe parameters, bodies, responses and security requirements. A security declaration states a requirement: applications and gateways still have to enforce it.
| Element | What it describes | Additional verification |
|---|---|---|
| Schema | Data structure and constraints | Actual validation and business rules. |
| Documented response | Expected status and content | Conformance of real responses. |
| Security requirement | Declared mechanism and permissions | Effective per-operation access control. |
| Example | One illustrative case | Consistency, no secrets and edge cases. |
Review the contract before sharing it
- Check required fields, types, ranges, pagination, errors and media types. Use fictional examples consistent with schemas, without secrets or customer data.
- Compare the description with requests and responses in a controlled environment. Test missing credentials, insufficient permissions and separation between accounts.
- Review external references and the tools resolving them. Maintain a redacted public description and protect private environments and operations.
Maintain documentation as a product
Review differences at each change and assign an owner. An example or generated client can be structurally valid while missing a business rule. Interactive consoles need a suitable environment, limited permissions and clear identification of state-changing operations.
Primary references
Compare OpenAPI with the running service
A useful OpenAPI description includes failure responses, schemas and examples clients actually encounter. When the document and API diverge, an integration can pass a demo and fail in production.
- Compare success and error cases against the description.
- Document optional values, pagination and operation limits.
- Test a representative client before changing the contract.
Primary reference: IETF RFC 9457 — Problem Details for HTTP APIs. Related method: read the practical guide.
ZIP and TAR archives: extract within a directory and resource budget
Validate paths, links and expanded data before promoting files from an archive.
- Extract into a fresh non-public directory with minimal permissions. Reject absolute paths, traversal, links and special files unnecessary for the task. Check resolved destinations and collisions using target filesystem rules, including case. A textual path prefix alone does not establish containment.
- Set per-file and aggregate limits for written bytes, entry count, depth, elapsed time and process resources. Do not rely only on compressed or declared size. Reject nested archives unless needed; if allowed, share a global budget across levels. Maintain the library and its extraction filters.
- Test a ../ entry, absolute path, link, duplicate and budget overrun. Verify an interruption leaves an unpublishable batch and never replaces existing files. Check output types and contents before promotion; clean the isolated directory through a procedure that verifies its destination.
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Expected decision
Fictional example: a 2 MB compressed archive produces 600 MB against a 100 MB budget. Stop when actual written bytes exceed the limit and keep the batch unpublished even if its first files appear valid.
Python — tarfile extraction filters and further verification
Does a small archive or extraction filter guarantee safety?
No. A small archive can expand greatly. Add resource limits, path rules and validation of extracted files to the filters.
Primary reference: Python — tarfile extraction filters and further verification. Related method: read the practical guide.
API errors: types, statuses and evidence
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