you haven't worked in the industry long enough if you haven't encountered poorly constructed/documented API integration from vendors.

the ideal world you described does not exist on this planet.