Separate evidence from inference
Every statement in a recovered API document falls into one of two groups. Code tells you that an endpoint exists and how the client builds the call. Observed traffic tells you what the server does with it. Keeping the two apart is what makes the document trustworthy, because a reader can tell which parts will survive a server-side change and which are observations from one session.
Label inference explicitly. A path from an interface declaration is strong evidence that the endpoint exists. A response shape inferred from one successful call is weaker, and a field that appeared in one response may be absent in another. Documentation that blurs those levels gets treated as wrong the first time it misleads someone.
Work from the transport outward
Fill the document in dependency order. Each layer constrains the next, and filling the authentication section after the endpoint list means rewriting the endpoint list.
- Hosts and environments, including which endpoints use a different host and what selects between them.
- Authentication: how a session begins, what the client stores, how long it lasts and how refresh works.
- Content types and serialisation, including any envelope that wraps every payload.
- Endpoints, one entry each, with HTTP method, path, parameters and body.
- Response shapes, split into the success case and the error cases.
- Sequences, for flows that only work in order.
Order the entries the same way every time. A reader who learns where to find the parameter table on the first endpoint will look in the same place on the next one, and consistent layout is what makes a long document usable during debugging.
Write one entry per endpoint
An endpoint entry earns its place by answering questions a caller will have while writing code. Include the resolved path with placeholder syntax, the verb, every parameter with its location and type, whether each parameter is required, the request body shape when a body exists, and at least one real response. Note the headers the endpoint requires that are not part of authentication, because those are usually computed and easy to overlook.
Keep example values. A shape without an example invites the reader to guess at formats: whether an identifier is a string or a number, whether a timestamp is seconds or milliseconds, whether an empty collection is an empty array or a missing field. Real values answer those questions faster than any type note.
Capture errors on purpose
Error behaviour is the part of an undocumented API that nobody has written down anywhere. Produce it before you document it: repeat a token that has been invalidated, send a request with a missing parameter, use a value outside an accepted range, and call an endpoint out of sequence. Record the status code and the body for each case.
The distinctions that matter to a client author are which conditions are retryable, which require a fresh session, and which are permanent. Those three categories change the retry logic someone writes, and they cannot be inferred from a success example.
Describe flows, not only calls
Individual endpoints rarely explain a feature. A checkout, a booking or a message thread is a sequence with state carried between calls. Document the order, the values passed from one response into the next request, and the point at which a failure invalidates earlier steps. Where a client can safely resume a flow and where it must restart is a question the app's own recovery code already answers, so read it rather than guessing.
Publish it in a form that stays useful
A document in prose drifts. A machine-readable description next to the prose does not: an OpenAPI document, a Postman collection or a typed client can be executed, which means every claim in it can be checked. Generating those artifacts from the same extraction keeps them consistent with each other and gives reviewers something to run.
The deliverable that gets used is the one that arrives with working examples. A written specification and an executable collection produced together are what the undocumented API work hands over, and the same material sits alongside the API documentation deliverable when a team needs the reference rather than the code.
Related work
Reviewed 28 September 2026 · SReverse research desk