A new supplier arrives as a PDF, credentials and a sandbox URL. The temptation is to open the document at the first endpoint and start typing, because the first endpoint is a search and a search looks easy. I have stopped doing that. The first pass is reading, against a fixed list of questions — none answered by the endpoint list, every one of them deciding the shape of the module I am about to write.
Auth, and how a credential rotates
What the credential is: a static key, a login returning a token with a lifetime, a per-request signature. Then ask what the documentation almost never answers. How does it rotate — who issues the new one, does the old one keep working while the new one is live, can I swap it without a deploy? A credential that rotates with no overlap window is an outage scheduled by someone else on a date you are not told, and knowing that on day one means it lives in configuration from the first commit.
Is search one call, or a call and a wait
Does the supplier answer on the same connection, or hand back a token and expect polling? This decides which execution model the module fits — the platform runs an asynchronous one and a synchronous one behind the same public contract — and where the supplier's latency lands: inside one call it competes with a hard search deadline, spread over polls it becomes a question of how many polls are worth making.
What is an offer, and how long does it live
Whatever the customer picks has an identity, and I want three things about it: what it is made of, whether it is stable when the same search runs twice, and how long the supplier still recognises it. Some tokens are opaque and short- lived, some structured and effectively permanent, some neither while the document declines to say which. It matters more here than in most places, because cross-call state rides inside a composite versioned offer ID decoded at prebook rather than a server-side session — the answer decides what gets packed in and what can be re-derived.
Is booking idempotent, and if not, what can I look up
Does the supplier accept a reference of mine and refuse to act on it twice? If yes, the hardest story in the integration — the timeout that lands while money is in flight — is mostly written already.
If no, the follow-up is the one that matters: what lookup exists? Can I search their bookings by my own reference, by date, by traveller name — by anything I still hold after a timeout? Neither idempotency nor a usable lookup means every ambiguous booking is reconciled by a human, and that belongs in the estimate, not in a surprise three weeks later.
Where do errors live, and which of them are yours
Some suppliers answer HTTP 200 with a failure in the body, which is well known enough. The subtler question: is there a stable machine-readable code, or is the only distinguishing feature a sentence somebody will reword next quarter? And which errors mean retry, which mean stop, which mean stop and tell a person?
Are the policies structured
A cancellation policy as a deadline and an amount can be filtered on, compared, acted on automatically. The same policy as a paragraph of prose can only be displayed. That one answer decides whether a whole class of features is possible here, and no downstream cleverness recovers a structure that was never sent.
What the rate model implies
Then the question behind the largest fork: does one token book N rooms, or is each room priced independently? The platform documents two offer patterns because suppliers genuinely differ here — A returns a single token that books N rooms; B prices each room on its own, and the offer list is the materialised matrix of valid combinations. Reading it wrong does not fail loudly. It fails as a two-room booking where the second room quietly takes the first room's price, found later in an invoice. Every integration declares its pattern, and this paragraph of the document is where that declaration comes from.
Limits, and what the sandbox will not tell you
Rate limits, concurrency caps, maximum occupancy, how far ahead dates may go. Then the more useful half: list what the sandbox cannot show you. It is usually a small fixed dataset with generous limits that never fails — no throttling, no production latency, none of the variety in real cancellation policies, none of the errors that exist only because real inventory sells out. They all arrive on the first day of production traffic.
Then: the error catalogue before the happy path
When I start reading endpoint by endpoint, I read the error catalogue first. The happy path is one paragraph long and you get it right almost by accident. The error list is where the supplier's real model of the world shows through: which states they believe exist, which of them they bother to distinguish, what they think is your fault. If there is no error catalogue at all, that is the most useful thing learned so far, and it goes in the estimate.
Capture the first real call, and write the mapping down
The first time the credentials work, save the whole exchange untouched. The document says what the supplier intends; the capture says what it does, and where they disagree, the capture wins.
Then write the field mapping where the next person will find it: their field, our field, the transform, and the case that convinced me. The last column pays for itself — in a year the mapping looks arbitrary, and only that note explains why it is not.
The estimate comes out of the reading
Endpoint counts are how integration work gets estimated by people who have not read the document. Two suppliers can each have six endpoints. One is synchronous JSON, idempotent on our reference, structured policies, pattern A — a few days. The other polls for results, has no idempotency and no lookup by our reference, prices every room independently and writes its policies as prose — weeks, and the weeks are in reconciliation, not in HTTP.
I have not correlated these answers against the time each of the roughly ninety integrations actually took, so there is no table to publish. What I can say is that every estimate I have given from an endpoint count was wrong in the same direction.