Bad API documentation is common enough that it should be treated as a normal engineering constraint, not a surprising exception.
The goal is not to complain about it. The goal is to build a process that gets you to the truth quickly and safely.
Start with the real output
The documentation tells you what the API wants to be. The response body tells you what it is.
When I need to understand an unfamiliar integration surface, I start by capturing actual requests and responses for the most important flows:
- authentication
- list endpoints
- record detail endpoints
- create or update actions
- error responses
Do not rely only on happy-path examples. A lot of useful understanding comes from:
- partial data
- null fields
- inconsistent types
- validation failures
- rate-limit behaviour
Build a field map early
As soon as the real responses start to make sense, create a field map.
That can be a simple table covering:
- field name
- observed type
- whether it is required
- whether it is stable
- internal meaning
- transformation needed before use
This saves time later because you stop rediscovering the same truths while writing code.
Look for the edge cases that shape the integration
The most important behaviour is often not the obvious behaviour.
Questions worth answering early:
- Are identifiers globally unique or only unique inside a tenant?
- Are timestamps always in the same format?
- Does pagination behave predictably?
- Can fields disappear without warning?
- Do status values change vocabulary between endpoints?
- Is the API eventually consistent?
These details usually matter more than whether the first request worked.
Build thin probes before building the full integration
Before I write the final production flow, I prefer building small inspection tools:
- a quick fetch-and-log script
- a schema snapshot utility
- a field comparison script between endpoints
- a test import for a small known dataset
These probes help answer questions cheaply before the integration code gets heavy.
Document what the API actually does
When the docs are weak, your internal notes become part of the system.
Write down:
- the assumptions you validated
- the assumptions you could not validate
- the transformations you applied
- the failure modes you observed
- the decisions you made because of the API's behaviour
That documentation is not ceremony. It is part of making the integration maintainable.
A good integration is not just a connector
The real work is not only making one request talk to another request.
The real work is making unreliable external behaviour safe and understandable inside your own system.
That means the final integration should aim for:
- clear transformation rules
- obvious error handling
- readable naming
- low-surprise behaviour
- enough documentation that the next person is not forced to reverse-engineer it again
When the docs are bad, the engineering job gets more investigative. That does not make it messy by default. It just means the process needs to be more deliberate.