API Design and Third-Party System Integration

Two engineers are looking at the same API. One is designing it; the other is trying to integrate it. They are doing the same job from opposite sides of one contract — and almost no course teaches it that way. This one does. You already call HTTP endpoints. What you may never have been taught is the craft underneath: why a retried `POST` quietly double-charges a customer, why your "v2" broke every consumer the morning it shipped, why the OAuth flow you copied from a blog trusts a token it never actually verified. These aren't exotic bugs. They're the default outcome of treating an API as "just call it." So we build the durable primitives instead of one vendor's SDK. On the design side: resources and status codes that mean what they say, machine-readable errors (Problem Details, RFC 9457), idempotency keys, pagination that survives a moving dataset, an OpenAPI contract you can version without betraying the people depending on it. On the integration side: a client with real timeouts, retries with backoff and jitter, circuit breakers, webhooks you verify and de-duplicate before you trust, an anti-corruption layer so a vendor's schema change doesn't ripple through your code, and credentials you can actually rotate. Along the way we settle the things that changed while no one told you: authentication is not authorization, an ID token is not an access token, PKCE is now mandatory, a JWT is signed but readable — so you read the specs instead of folklore. It ends where real work does: a payment integration and a public API, built end to end, and a checklist you can run on anything.