Search
Enter at least two characters without personal information.

    LibraryArticles & FAQ Your projectRequest a quote
    LanguageEN
    Practical guides

    Document and test an API from its use cases

    A useful API lets another team understand what it can request and what it will receive. Its contract should be testable, versioned and consistent with the operating service.

    Go to the method

    Printed diagrams and laptop displaying code
    AI-generated illustration

    Choose tasks before addresses

    JavaScript decoding: numeric 9007199254740993 rounds; the string keeps its digits.
    Illustration · Standard JSON.parse demonstration: Number rounds this numeric token, while String preserves its digits. Agree text representation before conversion.

    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.

    Standard JavaScript JSON decoding: precision and type
    Demonstration JSON tokenDisplayed JavaScript valueInterpretation
    90071992547409919007199254740991Safe integer in this example
    90071992547409929007199254740992Exactly represented, but outside the safe integer range
    90071992547409939007199254740992Rounded 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.

    Four responses from a fictional API and their client implications
    Planned responseEstablished factConsumer check
    201 CreatedResource createdCheck the Location required by this contract and the created identifier
    202 AcceptedProcessing accepted but incompleteRetain the tracking reference; await the final result
    204 No ContentAction succeeded with no response bodyDo not attempt JSON decoding of an empty body
    422 Unprocessable ContentInstruction understood but cannot be processed under the ruleRead 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

    1. Two reads of r7
    2. First write: r8
    3. Stale write: 412
    4. 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.

    Two editors, one current version: a fictional test sequence
    StepVersion and requestExpected result under this contract
    Both editors readETag: "r7"Each keeps the validator with their draft.
    First saveIf-Match: "r7" → version "r8"The first editor’s correction is retained.
    Stale second saveIf-Match: "r7"; current version "r8"412; do not replace the saved correction.
    Explicit reconciliationRead "r8", compare, then decideKeep the draft and check permissions before another write.

    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.

    Distinguish apparently similar API responses
    Situation or settingWhat it meansUseful check
    Empty listThe request succeeds, but no items match.Check the documented model, item count and next-page behaviour.
    Missing field, null or empty stringThese representations need not mean the same thing.Document each allowed case and test clients consuming the field.
    Object outside the authorised scopeKnowing 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

    Content updated on

    Documented reference points for this topic

    Documented reference points for this topic
    ReferenceValue or syntaxScope
    RFC 8259 · JSON
    application/json · UTF-8Standard JSON permits neither comments nor trailing commas; strings use double quotes.
    RFC 3339 · Date-time
    2026-10-22T09:00:00+02:00The explicit offset relates local time to UTC; this example is not an appointment.
    HTTP · If-Match
    If-Match: "r7" → 412If-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 Required428 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.

    Separate HTTP status, JSON and business outcome

    Choose a fictional exchange and try reading it locally. HTTP success, readable JSON and a completed operation require separate checks.

    These excerpts are incomplete and use demonstration addresses. The trial creates a Response in memory: it contacts no server and simulates neither network, cache nor business processing.

    200A new complete representation
    What it means
    In this excerpt, the server answers a conditional GET with a JSON body and the demo-v2 validator.
    What to check
    Compare If-None-Match, ETag and the body revision. The local trial parses the JSON supplied in this example.
    Watch out for
    A 200 status guarantees neither valid JSON nor correct business data. Successful parsing here does not validate your own data schema.
    Fictional exchange excerpt
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202Accepted, processing still pending
    What it means
    202 indicates acceptance for processing, not completion. The fictional body reports queued.
    What to check
    Keep reference DEMO-42 and follow its state under the API contract, including access rights and retry limits.
    Watch out for
    Response.ok is true for this status. Neither that value nor readable JSON proves completion. The excerpt’s fields and monitoring address are fictional conventions.
    Fictional exchange excerpt
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204Request fulfilled, no response body
    What it means
    204 indicates that the server fulfilled the request without response content. This excerpt transmits no JSON.
    What to check
    Handle the absent body according to the contract. Establish exactly what the receiving endpoint confirms before reporting an outcome to the visitor.
    Watch out for
    Parsing the empty body as JSON fails even though Response.ok is true. For a webhook, the confirmed operation may be receipt; subsequent business actions still need reconciliation.
    Fictional exchange excerpt
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304Copy revalidated, no new body
    What it means
    304 answers a conditional request: the stored representation can be reused. The 304 response supplies no new body.
    What to check
    Compare the sent validator with the available demo-v2 copy. Correct interpretation also depends on that stored copy.
    Watch out for
    The trial constructs an isolated 304 Response, not an HTTP cache. During a real fetch, the browser cache can provide the stored response: network status and script-visible status can differ.
    Fictional exchange excerpt
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    Technical references : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    Acceptance matrix to adapt to your project

    These proposed checks use synthetic cases. Decide the required behaviour with the team, record the result and assign unresolved gaps before release.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Test cases, expected outcomes and useful evidence
    CaseExpected outcomeEvidence to retain
    Present and absent resourcesEach outcome matches the documented status and response model.Method, path, test identity, received status and body for an existing then missing resource.
    Out-of-range parameterThe refusal is understandable and exposes no internal stack trace.Public message and result retained in the acceptance matrix.
    Two permission levelsA forbidden resource remains inaccessible even with a known identifier.Compared results using two synthetic accounts with explicitly different permissions.
    Pagination and changed filterToken handling and journey restart behaviour are defined.Ordering, returned identifiers and rules applying when the filter changes.

    Frequently asked questions

    Which API checks add value beyond documentation?

    Choose an important operation and compare documented examples with actual responses: valid data, missing fields, unknown identifiers and an account without permission. For lists, check pagination and empty results. Record status, expected structure and observed effect without secrets. Returning JSON alone establishes neither permissions nor contract stability.

    How do you check that CORS does not hide an authorisation flaw?

    Separate browser-readable origins from operations authorised for an account. In a test environment, check object and operation permissions using designated test accounts. A response unreadable by browser script may still be accessible to another client; the service must enforce access rights.