I’ve been thinking about how teams actually work through vendor API documentation, and I realized I don’t really know how it goes in practice.

On a small integration it’s usually simple. You pick the four or five endpoints you need and ignore the rest. But on bigger ones (ERP, banking, logistics, healthcare), it feels like the team ends up needing most of the document, and the work gets split between people by section.

For those of you who’ve done this recently:

Did you use a few endpoints or most of the vendor’s API? Did you split the sections between several engineers, or did one person own the whole integration? How did you keep everyone working from the same understanding of the docs, especially if they were a PDF or a messy wiki? If the vendor changed something later, how did you find out?

Mostly curious how common each situation is. Any war stories welcome.

Just got handed a vendor integration where the entire “documentation” is a 60-page PDF. Half the endpoints are in screenshots, and one of the auth examples was wrong, which I found out the hard way.

My process is the same every time: read it, retype everything into Postman, write my own types, and hope for the best. It takes forever, and I’m never fully sure I got it right.

What bugs me even more is that vendors update these docs every few months and don’t tell anyone. You only find out when something breaks in production.

So how do you all handle this? Do you paste it into an LLM and hope for the best, build the spec by hand, or ask the vendor for something better (and do they ever actually reply)? And how do you even know when they’ve changed something?

I’m also curious if this is just me, or if everyone has a graveyard of half-finished Postman collections.