Estimated reading time : 8 min · Published
Choose tasks before addresses
List uses such as finding a product, reading availability, updating a record or tracking processing. Define authorised people and systems for each operation. A public read API and an administrative API have different access requirements.
Prepare a request and response example for each essential task using synthetic values and explained fields. Distinguish stable identifiers, labels, units and dates. Define missing data instead of substituting plausible values for unknown information.
Specify large-identifier representation before choosing a JSON example. With binary64 numbers used by JavaScript Number, integers from −9007199254740991 to 9007199254740991 lie within RFC 8259’s exact interoperability range. The number 9007199254740992 is still representable, but is not a safe integer: its neighbour token 9007199254740993 rounds to 9007199254740992 in the standard JavaScript JSON decoding shown here.
The same identifier written as a JSON string retains its digits in this exercise. Agree this representation across producer, schema and consumer; converting an already rounded Number to text cannot recover the original value. Other libraries may preserve more precision, so test supported clients. Syntactically valid JSON does not guarantee value fidelity, and an identifier’s type should not silently change between responses.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Demonstration JSON token | Displayed JavaScript value | Interpretation |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Safe integer in this example |
| 9007199254740992 | 9007199254740992 | Exactly represented, but outside the safe integer range |
| 9007199254740993 | 9007199254740992 | Rounded value: original final digit lost |
| "9007199254740993" | "9007199254740993" | Exact string; text type agreed in the contract |
Describe an explicit contract
OpenAPI provides a language-independent description format for HTTP APIs, covering operations, parameters, responses and models. Choose a version supported by your tools and retain the document with the project; the newest version is not automatically the right fit for every toolchain.
Document usage limits, pagination, filters, ordering, errors and empty responses. Do not treat CORS as proof of authorisation. Review operation and object-level access controls with the technical team.
For a fictional enquiry-processing API, describe the four responses below separately. In this contract, 201 returns a created resource with its Location header; 202 supplies a tracking reference because processing is incomplete. Do not turn every 2xx response into “operation completed”. The client must read the status, headers and model specified for that operation.
A 204 response has no body to decode as JSON. In this example, a syntactically correct instruction that violates a business rule receives 422 with structured details in application/problem+json. If a status member is supplied, its generator must match it to the actual HTTP status; translated detail text must not become the software’s decision key. Document stable problem identifiers and the expected corrective action.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Planned response | Established fact | Consumer check |
|---|---|---|
| 201 Created | Resource created | Check the Location required by this contract and the created identifier |
| 202 Accepted | Processing accepted but incomplete | Retain the tracking reference; await the final result |
| 204 No Content | Action succeeded with no response body | Do not attempt JSON decoding of an empty body |
| 422 Unprocessable Content | Instruction understood but cannot be processed under the rule | Read the structured problem and offer an appropriate correction |
- RFC 9110 : HTTP Semantics
RFC 9110, consulted 22 October 2026: status semantics. The responses and required fields here define a fictional contract.
- RFC 9457 : Problem Details
RFC 9457, consulted 22 October 2026: problem format and the role of the status member.
Prevent one editor from overwriting another editor’s changes
- Two reads of r7
- First write: r8
- Stale write: 412
- Compare before resuming
Fictional scenario: two editors open record DEMO-17 with the strong ETag "r7". The first saves a correction; the current representation becomes "r8". The second still works from "r7". A conditional write can detect this difference before replacing the published version.
For an API supporting this contract, the client sends If-Match with the strong validator it received. The server compares the version before writing: our scenario specifies 412 when it has changed. W/"r7" is weak and cannot satisfy strong comparison. If-Match: * checks that a current representation exists, rather than that it has remained unchanged since reading.
Keep the second editor’s draft, read the current version and show the differences before submitting a new decision. Automatically replacing the validator with "r8" and resending the old draft would bypass the protection. The storage check and write must be indivisible; two concurrent requests with the same validator must not both overwrite the same version.
Concurrency control does not replace authentication, record permissions or field validation. Nor does it ensure a single execution of an external call. Test those properties separately and document missing preconditions; 428 can require a conditional request.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Step | Version and request | Expected result under this contract |
|---|---|---|
| Both editors read | ETag: "r7" | Each keeps the validator with their draft. |
| First save | If-Match: "r7" → version "r8" | The first editor’s correction is retained. |
| Stale second save | If-Match: "r7"; current version "r8" | 412; do not replace the saved correction. |
| Explicit reconciliation | Read "r8", compare, then decide | Keep the draft and check permissions before another write. |
- IETF · RFC 9110 § 13.1.1
IETF : Conditional writes and preconditions
- IETF · RFC 6585 § 3
428 · Precondition Required
Test boundaries and permissions
Try an existing object, a missing object, an invalid parameter and a list longer than one page. Check the next page for losses or repeats within the chosen update model. State limitations that the API cannot guarantee.
Use test accounts with different permissions. Attempt reads and changes outside permitted scope using synthetic data. Record expected statuses and useful messages without exposing internal traces or configuration secrets.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Situation or setting | What it means | Useful check |
|---|---|---|
| Empty list | The request succeeds, but no items match. | Check the documented model, item count and next-page behaviour. |
| Missing field, null or empty string | These representations need not mean the same thing. | Document each allowed case and test clients consuming the field. |
| Object outside the authorised scope | Knowing an address does not grant permission to read the object. | Test server-side permissions with two accounts and test data. |
Plan change and support
Distinguish an added field from a removed field or a changed meaning. Identify consumers before an incompatible change. Explain the transition period and how to detect integrations still using the earlier contract.
Deliver an executable example for a test environment, a test matrix and a technical contact. Relate observed errors to documented examples after release. Documentation limited to the ideal case leaves integrators without guidance for refusals and interruptions.
Primary documentation : OpenAPI Initiative : Specification.
Reference documents
- OpenAPI Initiative : Specification · Source consulted
- OWASP : Authorization Cheat Sheet · Source consulted
- MDN : CORS · Source consulted
- IETF : RFC 8259: JSON numbers · Source consulted
- TC39 : Number.isSafeInteger · Source consulted
Content updated on
Documented reference points for this topic
| Reference | Value or syntax | Scope |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | Standard JSON permits neither comments nor trailing commas; strings use double quotes. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | The explicit offset relates local time to UTC; this example is not an appointment. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-Match compares a strong validator before a write. Under the illustrated contract, a stale version receives 412; keep the draft to compare changes. |
| HTTP · 428 | 428 · Precondition Required | 428 lets a server require a conditional request. Document its use in the contract; the status does not itself provide locking. |
Dates indicate when references were consulted. These facts are neither a site audit nor an overall compliance statement.
