I'm definitely +1 on the OpenAPI requirement for v2 going forward. On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <[email protected]> wrote:
> I actually think that should be a hard requirement for the "next" API > ... if v2 is so different and awkward compared to a broadly adopted > standard, I'd say that's a short-coming of the v2 design. If we're > going to keep rolling out APIs that no standardized tooling supports, > just stick with v1, our users are no better off. > > On Fri, Oct 29, 2021 at 9:52 AM Eric Pugh > <[email protected]> wrote: > > > > I did try to write a OpenAPI specification for V2, and discovered how > much customization/specifics I would have to do, and gave up because we > were so very different. With the “experimental” tag, we could evolve > towards the OpenAPI spec standards if folks wanted to ;-) > > > > On Oct 29, 2021, at 11:48 AM, Timothy Potter <[email protected]> > wrote: > > > > Does the v2 API support OpenAPI? I looked over the docs and it seems > > like not, which is a shame. OpenAPI > > (https://swagger.io/specification/) opens up a mature ecosystem of > > tooling. The _introspection endpoint seems nice but if automated tools > > can't understand it, then our users can't auto-generate SDKs or > > interact with the API using tools like SwaggerUI, and so on. > > Once your API is OpenAPI compliant, you don't need to "document" it, > > tools will do that for you. > > > > I really think adopting this standard should be part of this > > conversation, otherwise, we're just re-inventing the wheel around API > > design and leaving too much heavy-lifting for ourselves. > > > > Tim > > > > On Thu, Oct 28, 2021 at 11:40 AM Jan Høydahl <[email protected]> > wrote: > > > > > > +1 to experimental (java level). > > In user facing docs and tutorials, we can encourage use, with just a > minor note somewhere that it may still change. > > When users report bugs there will always be a workaround — use v1 until > next release.. > > > > Jan Høydahl > > > > 27. okt. 2021 kl. 23:18 skrev David Smiley <[email protected]>: > > > > > > I agree that *very* few users use V2. Ok I do at work but it's maybe > one API endpoint so whatever. We should free ourselves from the burdensome > constraints of back-compat until V2 is sufficiently ready, whenever that > is. So I agree with labeling it experimental and we can elaborate on that > is the upgrade notes. Some APIs I think are only V2, so we can clarify > that we're not saying the underlying functionality is experimental. Not > only do we have to concern ourselves with inconveniencing some users, we > have to face the reality of our limited dev resources, and thus not make > the prospect of improvements too hard (nor on potential contributors). > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > > > _______________________ > > Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | > http://www.opensourceconnections.com | My Free/Busy > > Co-Author: Apache Solr Enterprise Search Server, 3rd Ed > > This e-mail and all contents, including attachments, is considered to be > Company Confidential unless explicitly stated otherwise, regardless of > whether attachments are marked as such. > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
