55 API Integration Jokes Every Backend Developer Knows

"The API is well documented." The last commit to the docs was in 2019.

I sent the request. I got back a 401. The body was empty. The support email took six business days.

"Just hit the endpoint." Which endpoint? The one in the docs, the one in the SDK, or the one that actually works?

The docs say the field is optional. The API returns 400 if you omit it.

Two kinds of integration engineers: Those who have logged the full response body, and those still trying to debug a 500 from a single line.

"Why is the webhook firing twice?" Because exactly-once delivery is a mathematical abstraction and your provider read it that way.

"The rate limit is 60 per minute." The rate limit is also 60 per second, depending on which docs page you find first.

I read the entire API reference. Nothing on the page mentioned the header that turned out to be required.

"It's RESTful." It is also using POST for everything, including deletes.

The example in the docs uses an API key that no longer exists. The example has worked exactly once, in 2017.

"Can you add a retry?" I added a retry. The webhook now fires four times.

The endpoint returns 200. The body says success is false. This is what dignity looks like.

"We follow the OpenAPI spec." The spec file was generated once. By hand. From the docs.

Pagination on this API is described as: cursor-based. The cursor is null on every page including the first.

"Just use our SDK." The SDK was last updated when Node 12 was current.

The sandbox returns success. Production returns 422. The error code is not in the docs.

I trust documentation. I just trust the curl example more.

"Why is the response a string?" Because somebody decided JSON inside JSON was a reasonable shape and shipped it.

The webhook fires. The webhook fires again three minutes later. The webhook fires a third time during the deploy and the database notices.

"It's idempotent." It is idempotent in the same sense that any operation is idempotent if you squint.

The auth flow has six steps. Five of them are documented. The sixth is the one that matters.

"We send a CSRF token on this endpoint." The endpoint is a JSON API with no cookies. The CSRF token is decorative.

I got a 429. There is no `Retry-After` header. There is no documented backoff strategy. I am alone.

"The pagination is straightforward." There are four pagination styles. They are all used. On the same API.

OAuth was simple before someone added a fourth grant type for this specific integration.

"Read the docs." The docs say to read the SDK source.

A senior engineer is someone who has typed `curl -v` and resigned themselves to reading three thousand bytes of TLS handshake to find a typo.

The status page says everything is green. The API is returning 502. The status page is also an API and it has cached itself.

"The token never expires." The token expires after 90 minutes. The docs were written by a different team.

I sent a JSON body. The API expected form-encoded. The error said: bad request.

"Use the v2 endpoint." The v2 endpoint redirects to v1 unless you set a header that is only documented in a blog post.

Postman has been open for so long the laptop fan is the only thing speaking in the room.

"We support webhooks." They send a POST with no signature, no retries, and a body that is sometimes XML.

"Why did the integration break?" They deprecated the endpoint last week and only mentioned it in the changelog, which is on a third domain.

The API is fast. The rate limit is generous. The pagination is sane. The documentation is accurate. I am dreaming.

"We use HMAC for webhook signatures." Great. Which header? Which encoding? Which secret?

Three teams integrated with the same API. Three teams reverse-engineered the same undocumented field. None of them talked.

"We added an enum value." That is a breaking change. They sent an email about it. The email went to a shared inbox nobody monitors.

I asked support a question. The answer was a link to the docs page that did not have the answer.

"Can you mock the API for tests?" The API has a sandbox. The sandbox has different behavior. The sandbox has different bugs.

The API charges per request. The API also retries on its end. My bill says it retried more than I did.

"Our API is RESTful and follows industry standards." It has an endpoint called `getOrCreate` that uses GET.

The webhook payload is documented. The webhook payload has six fields the docs do not mention.

"Use the bulk endpoint for performance." The bulk endpoint has a max batch size of 25 and a separate rate limit.

I am not afraid of distributed systems. I am afraid of the third-party SDK in the middle of one.

"Why is the response 1.6 megabytes?" They return every field for every object including the ones they tell you are deprecated.

The integration worked end-to-end. For one user. In the staging environment. On a Wednesday.

"It works in Postman." The most expensive sentence in integration engineering.

Every API has a hidden header that turns out to be required and is mentioned only in a Stack Overflow answer from 2018.

"How do we get notified of breaking changes?" LinkedIn, mostly.

I named the file `final_integration_v3_real.py`. There are seven files.

"The error code is 422." The message is `validation failed`. No field. No reason. No path.

The provider added a new required field on Tuesday. The integration broke on Wednesday. The blog post about it went up on Friday.

Some people meditate. I run the integration tests against the sandbox and accept whatever happens.

Integrating with a third-party API is basically: Learning a system that nobody on your team built, that nobody at the vendor still works on, and pretending the resulting code is yours.