As a developer, I work with a lot of APIs (if you don't know what an API is, try google). Very few of them are well documented. Some have no documentation whatsoever, some have way too much information, but most of them are either half-documented or actually have erroneous documentation. Yeah, you heard me right, their documentation is frequently wrong.
I honestly don't know how that happens. I can understand a typo or three, and maybe they recently updated their API and forgot to change the docs. However, most of the errors I see are so glaring that none of the developers could look at that and say, "yeah, that's correct." It's not like documenting a REST API is all that hard. Here's an endpoint, here's what it expects (including optional data(, and here's what it sends back. Repeat for each endpoint.
It's truly rare that I come across an API's documentation and think, "Wow. That's clear and precise, and now I know exactly how it works". I'm not writing this post because that happened, I'm writing this post because, yet again, I've encountered API documentation so screwed up, it's not actually possible to make it work. I've recently answered questions in both StackOverflow and Reddit about this very same API and how to make something work. Only after I discovered the secret solution after hours of research and failed attempts.
Short answer, there's a hidden step that was undocumented, involving a hidden data key that they never mentioned. That's right, they just assume you know the name of the hidden key that they expect and that you can somehow, miraculously understand where and how to send it.
I actually saw the company post an answer to the Reddit question saying that "yes, the documentation was correct as written", and still ignoring the whole "missing data key" part of the flow. Yet more of their documentation shows responses that are, in fact, wrong again. Have you even tried to use your own API?
Seriously? You obviously didn't read your own documentation when you wrote it, and you clearly didn't read it again when people asked questions about it.
Get your shit together! Your documentation doesn't have to be perfect, but it at least needs to be correct. Maybe try having one of your other developers try building an integration from your own API. Every time they have a question about something, update your damned documentation!
