Request: Thorough documentation for the API endpoint about documentation HOT 7 CLOSED

Not to sound like a dick, but the code is open source. If you think that there is a lack of API documentation than you can easily look at the code yourself to figure out what what does what and what needs to be sent. In no means is it perfect, but it is at least a way people can figure out how to use the API. Also, API documentation for an open-source project is not really "essential", it's a nice to have for easier reference of how to integrate with the software.

The Dashflo API docs are sufficient for understanding the basics of how the API works, in no means is it perfect but it is a decent starting point for sure.

from documentation.

That documentation isn't perfect, but it is written and maintained by one of our community moderators @LeCodeCo and frankly without that work there wouldn't be any API documentation at all. We've internally discussed writing some official docs and it may happen, but right now there are far more important things I need to be getting done for this project, that that API documentation is at least sufficient.

If there are specific things you think should be expanded upon or are detailed in a confusing manner, please do include comments about that here so we can work on getting that addressed. However, to my knowledge, that documentation is actually quite good at covering all of the endpoints, and includes numerous projects utilizing the API that you can also take a look at to see more specific example cases. I don't see how it "barely covers 20% of the functionality", so if you could please expand upon that it would be appreciated.

The docs published on Dashflo are far from perfect. Crucial information such as the include query params is totally absent and there is no explanation of the possible outputs. For example, when fetching the server utilization, what are the possible values for attributes->state? The only example is of on. All you get is how to make some super basic requests and what the format of the output is.

Not to sound like a dick, but the code is open source. If you think that there is a lack of API documentation than you can easily look at the code yourself to figure out what what does what and what needs to be sent. In no means is it perfect, but it is at least a way people can figure out how to use the API. Also, API documentation for an open-source project is not really "essential", it's a nice to have for easier reference of how to integrate with the software.

The Dashflo API docs are sufficient for understanding the basics of how the API works, in no means is it perfect but it is a decent starting point for sure.

I totally get you here, but I only partially agree. Yes, the code is open-source, but it is not necessarily written in a programming language that the common user of the API is familiar with. And let's be honest, reading through the entirety of unknown code just to figure out something simple is not going to bring a smile to anybody's face.
I totally disagree that the documentation is not essential. Especially for open-source projects. The docs are made to give both basic and advanced knowledge of the software to the client. However, proper documentation is not only useful when a client is using the product, but it is also vital for new people who want to contribute and including to the ones who programmed it when it's time for an update.
I am speaking of my own experience as a professional full-stack developer when I say that it's the easiest to maintain the docs from the beginning of the development and keep them updated every night you finish something. I doubt one can perfectly document a piece of software that they are unfamiliar with and that is already developed.

Let's not fight on how important the documentation is. Ask any professional developer that you know.

I am not here to blame anybody for not documenting the software, nor am I here with some useless pretensions just to be a dick.

from documentation.

Those documentations are fine, multiple libraries were made with reference to those docs.

from documentation.

If referring to https://dashflo.net/docs/api/pterodactyl/v0.7/, no it's not fine. I fail to find any API documentation in this repository.

from documentation.

That documentation isn't perfect, but it is written and maintained by one of our community moderators @LeCodeCo and frankly without that work there wouldn't be any API documentation at all. We've internally discussed writing some official docs and it may happen, but right now there are far more important things I need to be getting done for this project, that that API documentation is at least sufficient.

If there are specific things you think should be expanded upon or are detailed in a confusing manner, please do include comments about that here so we can work on getting that addressed. However, to my knowledge, that documentation is actually quite good at covering all of the endpoints, and includes numerous projects utilizing the API that you can also take a look at to see more specific example cases. I don't see how it "barely covers 20% of the functionality", so if you could please expand upon that it would be appreciated.

from documentation.

Good documentation should clearly explain what each endpoint does, all data that it accepts (e.g. additional query parameters), what are all the possible values that can be expected (e.g. "on", "off", "offline", "error", -1, etc.) and what's their expected type (string, int, date, whatever). One can make their own assumptions by trying out all these themselves, but that's never recommended for applications in production.

And I will say it again, if I had the time to go through the entire code, I would document it myself to contribute to this project.

from documentation.

Thanks for the thought out response.

I get a few hours a week to work on this and frankly putting a good chunk of that time into writing API documentation will only further kneecap the already slow progress of the panel.

I'm going to close out this issue because I think it is something we can all agree has room for improvement, but is not something I am going to sit down and knock out in any reasonable time frame. As a fellow software engineer I understand the need for relevant and useful documentation. However, I am also fully aware of the other more important and time consuming parts of the development lifecycle esp. in a product that unfortunately does not have the luxury of a dedicated paid engineering team to maintain it.

I welcome the many users and companies building additional functionality off this software to send patches and documentation upstream in areas they find lacking. 👍

from documentation.