We came across an unusual scenario the other day, which, on the one hand, amused us a lot, while, on the other hand, once again confirmed the problems connected with the accuracy of API documentation.
One of our third-party advisers discussed their experience of work with external REST API.
In their projects, they frequently use external REST API services provided by various large companies (Facebook, Instagram, VKontakte, etc.). Unfortunately, they are frequently confronted with the fact that the official documentation for the external API does not correspond to reality. Developers are irritated when an endpoint returns incorrect or incomplete data that was specified in the document.
So, some time ago, the company decided that they would now WRITE THE DOCUMENTATION FOR EXTERNAL SERVICES BY THEMSELVES! And, what's more interesting, they got right to work: they now write and support documentation for third-party services by themselves!
Imagine the absurdity of the situation. A large company (for example, Facebook) publishes an external REST API and provides it with detailed documentation. Developers and users of this service find flaws in this documentation and find out that the REST API actually works a little differently, which is why they are constantly having integration issues. So, in order to avoid stepping on this rake over and over again, they devote all of their time and effort to create their own internal version of the documentation for the external service API. Well, that’s how much you can annoy the developer with the inaccuracy of the documentation!
You don't know whether to cry or laugh, as they say. This is, however, good news for JSight. This means that our experience is relevant, that it is not in vain that we are fighting first and foremost the ACCURACY of the documentation, not forgetting, of course, about the convenience for developers. The first version of our free tool will be available soon! Don't miss out on the chance to be one of the first to try JSight!