Plenty of supplier APIs ship with a PDF that’s six years old, examples that no longer match the responses and an error list that stops at three codes. Some ship with nothing at all. The supplier still wants you to connect, because it sells their inventory, and your business still needs it, because someone is copying availability into a spreadsheet by hand.
This is the approach we take. It’s mostly about not pretending to know what you don’t know.
Treat investigation as its own phase
The first mistake is quoting a fixed price for the build before anyone has looked at the API. If the documentation is weak, the real scope is unknown, and a price based on a guess ends in padding or in a dispute.
Split the work. Phase one is investigation: get access, make real requests, write down what happens. Its output is a short document describing the endpoints, the data shapes and the surprises. Phase two is the build, quoted with that document in hand. It costs a little more up front and removes the largest source of overruns.
Get everything you can from the supplier
Before reverse engineering anything, ask. A short, specific email often yields more than expected:
- A sandbox or test account, and whether it behaves like production.
- Rate limits, and what happens when you exceed them.
- Whether responses are cached, and for how long.
- A list of error codes, even an incomplete one.
- A technical contact who can answer questions.
- Whether the API version can change without notice.
Ask which fields are authoritative. A "price" field might be net, gross or per person, and the only reliable way to know is to ask or to compare against a booking you can see in full.
If the supplier has a booking site, use it
Where a supplier has its own booking website, that site frequently calls the same API. Open the browser’s developer tools, work through a search and a booking, and look at the network requests. You’ll see the endpoints, the parameters, the headers and the real responses.
Do this carefully and within what you’re permitted to do. Check the supplier’s terms. Where possible, tell the supplier what you’re doing and why, because a conversation now is easier than a blocked account later. Do not hammer their servers while exploring, and don’t use anyone else’s credentials.
Record real responses and build fixtures
Save the requests and responses you capture. Strip anything sensitive. These recordings become your fixtures: files your test suite replays, so you can develop and test without calling the supplier every time.
Fixtures let you check how your code handles the real shape of the data, including the odd cases: an empty list that arrives as null, a date in a different format on one endpoint, a number sent as a string. Collect a variety, and include responses for errors and for products with unusual attributes.
Assume what you can’t observe
Some behaviour you won’t see during investigation: how the API behaves under load, what it returns during an outage, how it handles two requests for the last room at once. Design for the worst case instead of waiting to find out in production.
That means:
- Timeouts on every request, shorter than you think you need.
- Retries with backoff, so a brief failure doesn’t become a burst of repeated calls.
- Idempotent operations. HTTP defines some methods as idempotent, meaning a repeated request has the same effect as one, and clients may retry them automatically after a connection failure. For operations that aren’t naturally idempotent, such as creating a booking, use an idempotency key or check for an existing record before you retry.
- A queue between your system and the supplier, so a slow supplier doesn’t make your own site slow.
- A dead-letter queue for messages that keep failing, where a person can inspect and replay them.
- A rate limiter on your side, below any documented limit.
None of this depends on documentation. It depends on assuming the other end will sometimes be wrong, slow or silent.
Validate what you receive
Do not trust the response shape just because it matched yesterday. Validate incoming data against the schema you built from your fixtures. If a required field is missing or a price is negative, stop and flag it, and don’t store it or quote from it.
When validation fails, log the whole response, because it’s exactly the evidence you’ll want when you write to the supplier.
Reconcile on a schedule
A scheduled comparison between what you hold and what the supplier reports catches drift quietly. A daily job that lists differences, such as an availability count that doesn’t match or a price changed without a notice, turns silent errors into a short report.
Flag the differences. Do not overwrite automatically, because a difference could be your bug as easily as theirs. A person decides which side is right.
Monitor the integration, not only the server
A server can be healthy while the integration is dead. Alert on integration-specific signals: no successful sync in a set number of hours, a spike in validation failures, the dead-letter queue growing. The alert should name the integration and the failure, not just say "error".
Write the documentation they didn’t
At the end, write down what you learned: each endpoint, each field with its meaning and units, error codes you found, rate limits, quirks and how your code handles each one. Keep it in the repository.
This document is part of the handover, and it’s useful to the supplier too. Sending it to them, politely, sometimes leads to the official documentation finally improving. At minimum, it means the next developer isn’t starting from zero.
When to push back
Some APIs are too unreliable or too restricted to build a business process on. If the supplier changes the format weekly, forbids automated access or offers no sandbox and no contact, tell your client plainly. An alternative channel, a different supplier or a managed file transfer may serve better than an integration that will break every month.
If you have a supplier API in this state, our integration engineering service starts with the investigation phase described here.