Alright, it seems like there's general agreement that we should
designate v2's evolving nature in some way, and that this should allow
us to break backcompat if necessary on v2 going forward. There were
at least 8 voices in favor with the only disagreement being Gus who
expressed concern on the backcompat front but didn't press the point.
(Gus - I don't want to mistake politeness for "not pressing the
point". if I'm underestimating your level of concern and you're at
"veto", just let me know.)
With that in mind, I think the next steps here should probably be to:
1. decide what label or term we want to go with ("evolving"?
"experimental"? "beta"?), and
2. figure out what the best way to publicize change in policy.
For (1) my vote is probably still "experimental". If others care
enough to chime in though I'm happy to go with whatever's most
popular.
Eric expressed some concern that "experimental" implies that v2 might
not get adopted. IMO that implication might not be a bad thing;
Houston is talking about making the APIs more RESTful, Tim wants to
add OpenAPI support, and there were lots of other changes suggested in
this thread alone. I'm sure something called "v2" will be adopted at
some point, but if even some of those projects attract attention "v2"
could look very different from the v2 that users might know today. So
"experimental" seems accurate to me.
For (2), I imagine it'd be sufficient to (a) mention the policy change
in release notes, and (b) update the ref-guide's "v2-api.adoc" to
cover this in some detail. We could do other things in addition (an
ANNOUNCE email, etc.), but IMO those seem like overkill. Thoughts?
Best,
Jason
On Wed, Nov 3, 2021 at 2:27 PM Timothy Potter <[email protected]> wrote:
>
> No relation to manning or the author but there's a MEAP book on sale
> about OpenAPI -->
> https://twitter.com/LukasRosenstock/status/1455915170614677507
>
> On Mon, Nov 1, 2021 at 8:40 AM Jason Gerlowski <[email protected]> wrote:
> >
> > I don't know OpenAPI well enough to have an opinion on whether it's
> > right for Solr, except to say that if we do want OpenAPI then an
> > "experimental" designation sounds helpful for giving us flexibility to
> > change our APIs as necessary.
> >
> > I recently created SOLR-15734 as an umbrella for tracking and
> > discussion around what all needs to be done to get v2 ready to
> > supplant v1. Just an FYI in case any of you guys create an OpenAPI
> > ticket - seems like a good place to put it under.
> >
> > On Fri, Oct 29, 2021 at 3:17 PM Jan Høydahl <[email protected]> wrote:
> > >
> > > Agree. Solr too often suffers from “not invented here” syndrome.
> > >
> > > OpenAPI is closer to REST, , i.e. using the http DELETE verb for deleting
> > > resources etc. I think the only selling-point for v2 was that it allows
> > > mixing lots of actions like adding and deleting in the same atomic
> > > request. But if designed carefully we could still allow that as “bulk”
> > > syntax in OpenAPI for the type of APIs where it makes sense, such as
> > > atomically switching an alias.
> > >
> > > Sendt fra min iPad
> > >
> > > 29. okt. 2021 kl. 18:14 skrev Houston Putman <[email protected]>:
> > >
> > >
> > > 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]
> > >>
> >
> > ---------------------------------------------------------------------
> > 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]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
