The Importance of Updating the API documentation
This week, I have been dealing with the interesting bug. In one of the third part APIs, that we integrate with, one of the endpoints started to return HTTP status code 400. But we did not change the code in the meantime, the documentation still said it should be a valid endpoint, and the other endpoints still worked.
So I wrote to the support, not expecting any answer. I mean, we just develop the integration, I am not actually a paying customer. I wrote about the problem.
I did get a response really quick. And after providing the account ID of the problematic case, they told me the actual cause.
They were creating the new endpoint for usage info (what we wanted to get) and I would need to to use this new endpoint, that she provided me. The documentation has not been updated to match it yet.
But even though the documentation was not updated yet, she was not allowed to share the information about the endpoint without an account ID. I wonder what the reason behind this was?
I mean, their account ID is just an integer. Based on the length, I would assume they are not random, so I think it would not be hard to guess a valid one in a couple of guesses. If each is done from the different email... does not seems to be done for the security reasons.
Updating the documentation was probably not done, because a lot of times this is something left for the end, and it might not get done, because something more important comes up. But still... they why control the flow of information through different channels?
I would prefer for these changes to be also reflected in the documentation by the time the old endpoint stop working. This would help to resolve a lot of problems without back-and-forth with support.