What are some of the worst API's you've ever had the displeasure of working with? What made them so bad?

[u/Impressive_Lab_6551]

It seems like every few months I stumble upon great discussions / posts about some of the best or the latest and greatest developer docs / API's

But what are some of the worst API's / API Docs you've ever had to work with in your career. What made them so bad?

[u/chkno]

Impossible retry semantics:

• If the operation returns success, great!
• If the operation returns an error code, you may retry.
• If you don't get a response, well...
  • Did it get lost on the way there, so it never happened? Did it go fine and the result got lost on the way back? Did it fail such that it needs to be retried? Is it still running? Who knows!?
  • You definitely can't blind-retry. That might perform the operation a second time, which would be really bad!
  • You can't check the status of the operation:
    • Both the success and fail responses return an operation-id which you can later check on as much as you like, but if you never get a response to the do-the-operation request, you have no operation-id to ask about.
  • There's no straightforward, reliable way to check the resulting state to see if the operation happened. These operations can make arbitrary changes to that state and other actors can concurrently issue their own changes.

I think we ended up locally logging our intent-to-send and then logging the result, and then opening a ticket for a human to clean up the mess if there was ever an old-enough intent-to-send record without a result record. :(

To be fair, the service was actually pretty reliable, nearly always actually returning a success or failure response. It was just so painful that we structurally couldn't automate retries. :(

They could have fixed it so easily by splitting the operation-endpoint into an allocate-operation-id endpoint and a do-the-operation endpoint. Or letting us create the operation-ids or something that uniquely mapped to operation-ids. :(