While documenting endpoints please use something like OpenAPI specification. The sidecar should expose this document itself so when I go to this and that URL, I see all endpoints, I put the payloads / parameters for them and I can just directly call that, no messing with curl / wget or programmatically or whatever like that. The barrier to exercise the basic functionality has to virtually not be there.
On Wed, Oct 2, 2024 at 4:13 PM Abhijeet Dubey <dubey.abhijee...@gmail.com> wrote: > Hi folks, > > I have been using Sidecar recently and have found some of its > functionalities to be quite useful. Hari and I are also working on CEP-40 > which aims to introduce live migration features in Sidecar in the > near future. > > However, as others have mentioned, I agree that it currently lacks proper > documentation. > > Since this is an official Apache project, I believe that creating > comprehensive documentation would be beneficial. This documentation should > include an overview, architecture, a list and description of various > endpoints, and some examples or tutorials on how to use Sidecar's features. > > This documentation would help people get started with Sidecar and lower > the entry barrier for many. We can update the documentation incrementally > as needed, along with future enhancements and new features. However, > creating some form of formal documentation would be very helpful. > > To this end I'm willing and highly interested in writing some form of > formal documentation for the Sidecar project. Please let me know your > thoughts/opinions on this proposal. > > > > On Wed, Oct 2, 2024 at 6:46 PM Štefan Miklošovič <smikloso...@apache.org> > wrote: > >> Totally agree with Jon here basically on all fronts. Apache Cassandra >> Sidecar was always a hard nut to crack for me, that is probably why I have >> not been involved with that a lot even that is a great tool to have and be >> invested in as I was writing my own sidecar and I found a lot of >> similarities and problems Apache's sidecar tries to fix. There was some >> invisible barrier I have never managed to jump over. I was looking around >> and I am very sorry if I just have not found it yet but there is not a list >> of endpoints a sidecar has, is there? In readme and dev docs there is just >> nothing. Taking it at a face value I just don't know what Sidecar is >> capable of and how to use it. I see in the commit history there is a bunch >> of commits mentioning S3 but it is a total blackbox for me as a potential >> user. >> >> On Wed, Oct 2, 2024 at 2:52 PM Jon Haddad <j...@rustyrazorblade.com> >> wrote: >> >>> I don't think we should release sidecar 1.0 without any docs. >>> >>> I took a look through the closed JIRAs to see what's there. Here's what >>> I found, please correct me if there's more: >>> >>> - Lots of stuff related to analytics. >>> >>> I would be pretty excited for this, but the analytics library only works >>> with single token clusters. Most folks don't run Cassandra this way. I >>> realize there's some element of everyone needs to scratch their own itch, >>> but I don't think we can really call this a useful feature if the >>> overwhelming majority of folks can't use it. I've worked with a couple >>> hundred teams over the years and can only think of 1 org outside of Apple >>> and Netflix that used 1 token, and It was a cluster that predated v-nodes. >>> >>> The analytics repo says it's compatible with Cassandra 4, but not 5. >>> >>> - Backup & Restore from S3 >>> >>> Is this compatible with other cloud providers or object stores? It >>> specifically lists S3 in JIRA. I haven't looked at the source yet. Am I >>> correct in reading it supports backing up snapshots, no continuous >>> backups? Seems like we should have at least feature parity with Medusa if >>> we're going to release something here. >>> >>> All the other closed JIRAs look related to these two items. So the >>> question is, are we releasing 1.0 as an limited S3 backup and restore >>> tool? One that prevents you from upgrading to Cassandra 5 if you happen to >>> use single token clusters? >>> >>> Who is the target audience? >>> >>> Jon >>> >>> >>> >>> On Wed, Oct 2, 2024 at 2:41 AM Dinesh Joshi <djo...@apache.org> wrote: >>> >>>> Currently the Sidecar has a lot of functionality that is immediately >>>> usable by the community. Apart from minor fixes, the AuthN/Z story would be >>>> wrapped up soon. Post this, I would propose moving forward with cutting a >>>> release with the existing feature set so we can get this in the hands of >>>> our community. >>>> >>>> On Tue, Oct 1, 2024 at 8:27 PM guo Maxwell <cclive1...@gmail.com> >>>> wrote: >>>> >>>>> Have the same question ： what ‘s the plan ？ >>>>> >>>>> Jeff Jirsa <jji...@gmail.com>于2024年10月2日 周三上午10:43写道： >>>>> >>>>>> >>>>>> >>>>>> On Oct 1, 2024, at 7:26 PM, Josh McKenzie <jmcken...@apache.org> >>>>>> wrote: >>>>>> >>>>>> However it is used by a number of other features as a dependency such >>>>>> as analytics, backup/restore, repair, metrics, and CDC >>>>>> >>>>>> It seems like a natural pressure relief valve for moving operations >>>>>> out of a core C* node that are well served out of process. >>>>>> >>>>>> >>>>>> Yea, but the point of the foundation is to RELEASE software for the >>>>>> public good, and the link asserting consensus was dec2018, so its’ 5.5 >>>>>> years and no releases. >>>>>> >>>>>> What’s the plan here? >>>>>> >>>>>> >>>>>> >>>>>> >>>>>> > > -- > *Abhijeet* >
