When I developed some of the original sidecar code, it was based on REST Easy, which would have allowed us to generate the spec automatically. I did this in a similar project.
That was removed here: https://issues.apache.org/jira/browse/CASSANDRASC-57 But unfortunately it looks like you can't generate the spec from the code. Disappointing, that functionality was really useful. I wish someone had asked me before gutting it. Jon On Wed, Oct 2, 2024 at 11:16 AM Štefan Miklošovič <smikloso...@apache.org> wrote: > Something like this: > > https://instaclustr.github.io/instaclustr-icarus-go-client/ > > On Wed, Oct 2, 2024 at 4:54 PM Štefan Miklošovič <smikloso...@apache.org> > wrote: > >> 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* >>> >>
