Issue in page REST

[nyh]

I would like to report an issue in page https://docs.scylladb.com//operating-scylla/rest

Problem

This page much too short and not at all helpful. User come up with issues like https://github.com/scylladb/scylla/issues/8132 because they have no example of how to use the REST API correctly,

Suggest a fix

Add at least one example of a full REST API request with parameters..

[tzach]

@nyh where can I find working examples?

[tzach]

BTW, long term solution is publishing the Swagger format.

[nyh]

@nyh where can I find working examples?

Let's ask @amnonh, he's the expert. I have a few examples in my own script, but maybe he has better ones. And the person writing this document should test the examples he or she is writing. This document can also reside in scylla.git's docs/ directory, so developers can be the one to write it and test it.

I don't know what you mean by "publishing the Swagger format", do you mean converting the swagger file into a document, offline? That would be good. But what we have today - that you need Scylla already running to investigate the REST API through the UI - is not good enough. People also need to know how to write the code without having constant access to a running Scylla.

[amnonh]

The reason the RESTFull API is not documented is becasue it's not aim currently for users rather for internal use. Originally, the idea behind swagger is that we would use it to generate the documentation, the swagger ui (the one you find when you look at http://{ip}:10000/ui ) actually has example for each command

[nyh]

The reason the RESTFull API is not documented is becasue it's not aim currently for users rather for internal use.

Then let's change the two-line document about this feature to say that it's an internal feature that should not be used. Or remove it from the documentation entirely... But as it stands, at least one user started to use it (https://github.com/scylladb/scylla/issues/8132) and made wrong guesses on what the API is, and Scylla just silently ignored the wrong parameter format, and when I wanted to point him to examples of the right API, I couldn't even find any.

Originally, the idea behind swagger is that we would use it to generate the documentation, the swagger ui (the one you find when you look at http://{ip}:10000/ui ) actually has example for each command

The idea of the world wide web is to have links. We should have documentation with permanent URLs, to which people can link, Google can find, etc. Having http://localhost/ui" is not enough.

[amnonh]

The reason the RESTFull API is not documented is becasue it's not aim currently for users rather for internal use.

Then let's change the two-line document about this feature to say that it's an internal feature that should not be used. Or remove it from the documentation entirely... But as it stands, at least one user started to use it (scylladb/scylla#8132) and made wrong guesses on what the API is, and Scylla just silently ignored the wrong parameter format, and when I wanted to point him to examples of the right API, I couldn't even find any.

Originally, the idea behind swagger is that we would use it to generate the documentation, the swagger ui (the one you find when you look at http://{ip}:10000/ui ) actually has example for each command

The idea of the world wide web is to have links. We should have documentation with permanent URLs, to which people can link, Google can find, etc. Having http://localhost/ui" is not enough.

you missunderstood me, the original idea was that when it will be public, we will generate HTML from the swagger and place it in the documentation site, I pointed to scylla ui as an example

[nyh]

Note also that although having full documentation of all the different operations would be nice, it's not actual the critical part in my opinion, because once you understand the basics of this API you can find the details in http://localhost:10000/ui. In my opinion it is more important (and also easier) to describe the basics of how to use this API and provide examples of how to pass parameters, etc. - just so users don't make mistakes like in https://github.com/scylladb/scylla/issues/8132 where the user found the right API operation, but used it wrong (assumed the parameters should be passed as JSON).

[stale[bot]]

Thanks for reporting. This issue has been automatically marked as stale because it had no activity for the last few months, and will be closed if no further action taken. If the issue is valid, please add a comment to keep it alive!

[tzach]

This is still valid, and still better to be fix in Scylla itself (or at least in tree doc)

[stale[bot]]

Thanks for reporting. This issue has been automatically marked as stale because it had no activity for the last few months, and will be closed if no further action taken. If the issue is valid, please add a comment to keep it alive!

[stale[bot]]

Thanks for reporting. This issue has been automatically marked as stale because it had no activity for the last few months, and will be closed if no further action taken. If the issue is valid, please add a comment to keep it alive!