How to reconcile API documentation with a changed endpoint

When you run this

An endpoint changed: a new parameter, a renamed field, a different status code, a stricter validation rule, a new error, a changed default. The published reference no longer matches what the API does. A reader who follows the docs now gets a surprise. Your job is to make the reference an accurate description of the endpoint's current behavior, verified against the running API, without inventing anything the API owner has not confirmed.

Inputs you need before you start

• The endpoint's identity: method and path, and the API version or release the change shipped in. Reconcile against one version; do not blend two.
• The current published documentation for that endpoint (the reference page, and any tutorial or how-to guide that calls it).
• The machine-readable contract if one exists: the OpenAPI description, the protobuf definition, the schema. This is a claim about the API, not proof of its behavior; treat it as a second source to reconcile, not the answer.
• Access to call the endpoint in a non-production environment with credentials that exercise the normal and the error paths.
• A named API owner who can answer "is this behavior intended?".

Deliverable

• The updated reference page (and any dependent guide), describing the endpoint as it actually behaves in the target version.
• A discrepancy report: every gap found, its resolution, and who confirmed it.
• A list of any behavior that is real but undocumented-by-decision, or that you could not verify, flagged explicitly and surfaced to the owner before publication.

Steps

1. Pin the version and gather the three views

Fix the exact version. Collect, side by side:

• what the prose reference currently says,
• what the contract (OpenAPI / schema) declares, if there is one,
• what the endpoint actually does when you call it.

2. Diff the contract against the prose

For the endpoint, compare the reference page and the contract field by field. Note every disagreement: a parameter in one and not the other, a type mismatch, a described error the contract omits, a required/optional disagreement, an example that does not validate against the schema.

3. Probe the actual behavior

Call the endpoint and record what it does, for each of:

• Parameters: every documented parameter, plus omitting each required one, plus an out-of-range or wrong-type value. Record the actual response.
• Success responses: the status code, the body shape, every field and its type, nullability, and whether the documented example still round-trips.
• Errors: trigger each documented error and each error you can find that is not documented (bad auth, missing field, malformed body, rate limit). Record the status code and the error body. Check the status codes against their defined meaning: a 200 carrying an error body, or a 400 where 409 fits, are findings. A 404 on an unauthorized request is not automatically a finding: RFC 9110 lets a server answer 404 instead of 403 to avoid confirming that a forbidden resource exists. Check the API's own documented disclosure policy first, and flag it only if the API states it distinguishes 403 and does not here.
• Examples: run every code sample and example request in the docs as written. An example that no longer works is a defect to fix or remove.

4. Classify every discrepancy

For each gap between the three views, decide which is right:

• Docs wrong, API right: the common case. The doc is updated to match observed behavior.
• API wrong, docs right: the endpoint has a bug. Do not document the bug as intended. Raise it with the owner and hold the doc change for that field until it is resolved.
• Both plausible, intent unclear: a question for the owner. Do not guess.

5. Resolve with the owner

Take the classified list to the API owner. Get a decision on every "API wrong" and every "intent unclear" item. Record who said what. Behavior the owner will not confirm does not go in the reference as fact.

6. Update the pages

Rewrite the affected reference sections to match the confirmed behavior: parameters, request body, every response and its fields, every error, the examples. Update any tutorial or how-to guide step that calls this endpoint. Keep procedures numbered and imperative; do not duplicate a procedure that already exists elsewhere, link to it.

7. Verify the rewrite

Execute a representative set of requests against the target version one more time: at least one success path and every error path, using the examples exactly as they now appear in the docs. Every documented example must run and produce what the docs say it produces.

8. Publish with the caveats attached

Publish the pages. In the discrepancy report and, where relevant, on the page itself, note anything undocumented-by-decision or unverified. Do not let an unverified claim ship silently inside otherwise-corrected docs.

Decision points

• There is no machine-readable contract. Step 2 is skipped; the observed behavior in step 3 is your only ground truth, so widen the probing.
• The endpoint is deprecated. Reconcile it anyway, and make sure the deprecation notice, the sunset date, and the replacement are present and correct. A wrong deprecation notice is worse than none.
• The change is part of a larger version bump with many changed endpoints. Reconcile one endpoint at a time against the same version; do not batch the verification.
• You find behavior that looks like a security issue (an error leaking internal detail, an auth bypass): stop, do not document it, report it through the security path, not the docs backlog.

If it goes wrong

• You cannot reach a non-production instance of the endpoint. You cannot verify. Do not reconcile from the contract alone and call it done: mark the page as unverified against running behavior and escalate for test access.
• The owner is unresponsive and the docs are actively misleading. Publish a minimal correction that removes the wrong claim (rather than replacing it with an unconfirmed one) and flag the open questions, rather than leaving known-wrong text live.
• A documented example depends on data you cannot recreate. Rewrite the example to use data a reader can create, verify that version, and note the substitution.

Confirm it worked

• Every parameter, response field, error, and example on the reference page matches a call you made against the target version.
• Every code sample and example request in the docs runs as written and produces the documented result.
• The machine-readable contract and the prose agree, or the disagreement is recorded with the owner's decision.
• The discrepancy report lists every gap, its resolution, and the confirming owner.
• Nothing unverified or undocumented-by-decision shipped without an explicit flag.