I don’t understand why full documentation for all API endpoints doesn’t exist. The original documentation was released to the public on December 2014, and here we are 6 years later and the documentation is still half-baked.
Why is this? The lack of good documentation and the suggestion to reverse-engineer the API is a significant barrier for developers looking to use the API.
@justin My specific example is I’m slowly working on rolling out a Discourse API Python wrapper, and I find the lack of proper documentation overwhelming. I already have to hand-test every single endpoint, but many of those endpoints are either not documented or are incorrectly documented.
It’s directly stated at the top of the documentation that the API isn’t fully documented. I want to know: Why?
Out of interest why don’t you simply support what is required until you hit a new unsupported requirement at which point reverse engineer it? That’s a lot easier than aiming for 100% and it’s pointless wrapping calls that will never get used? Especially since you will be supporting a moving target. Make your life easier?
I understand that this can be reverse-engineered. It’s just a little frustrating to have to do this. The API was created by humans who must know how it works, why can’t those humans write it down so others can be informed?
I don’t feel like this is a big ask. Good documentation is crucial in any project.
As with anything, it’s a matter of resources and priority. The API surface is huge. Technically, it’s everything - everything is accessed via the API, hence why reverse engineering works. We’ve chosen to focus our finite engineering time on fixes, features, performance etc, rather than on documentation. Our product direction is largely driven by our customers, and our community. To my knowledge, no customer has ever asked for 100% API documentation coverage. When customers do ask about something that is missing or unclear, we add it. Therefore, 100% coverage it hasn’t been a priority.
At this time, the API docs are manually curated. This is obviously not a sustainable method, but at the moment it’s what we have. Refactoring the API docs system to be generated programmatically is a “todo” item, but it’s not currently slated for any specific release, so there’s no timeline for completion.