You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@solr.apache.org by Jason Gerlowski <ge...@gmail.com> on 2021/10/26 19:10:31 UTC
Should v2 API be "experimental"
Hi all,
I'm starting this thread to highlight a subject that came up in the
recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
should the v2 API be considered "experimental"?
We haven't explicitly called the v2 API experimental up to this point,
but I'd argue that in essence it already is. In previous releases it
was largely undocumented, had little or no SolrJ support, missed
parity with v1 in terms of endpoints and parameters, and wasn't
included in test randomization. It's hard to imagine how someone
could have been using the v2 API nontrivially in our past releases.
Treating v2 as "experimental" just feels much more like calling a
"spade" a "spade", and sends a more accurate signal to our users. It
would also have practical benefits: experimental code is traditionally
free from backcompat guarantees, so an "experimental" designation
would remove a big impediment for those improving the v2 API.
Knowingly setting backcompat aside is always scary, and of course, we
don't have any means to know for sure how many users v2 has today.
But if we judge from the few signals we do have, the number must be
very small. e.g. The last user-list email that mentions a v2 API path
is "Atomic update error with JSON handler" from May of 2018!
Potential backcompat breaks might inconvenience that small set of
users, but that inconvenience would be vastly outweighed by the
benefit to all our users of getting a cleaner, more consistent API out
sooner.
Anyway, that's my pitch. Would love to hear what people think about the idea.
Best,
Jason
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Gus Heck <gu...@gmail.com>.
> But I think there's a strong case that these users are a tiny
> tiny minority out there: see the past lack of v2 docs, SolrJ support,
> mailing list traffic or bug reports on v2, etc.
>
Well I'm guilty of having documented it in documentation I wrote or
significantly modified, which ironically seems possibly problematic now.
Query to the Users list on how many folks are using it might be of
interest.
> On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
> >
> > > While the v2 has been out for a long time, do we actually have
> evidence that it is widely used and has significant code written against it?
> >
> > I don't think anyone uses V2 APIs. No one wants to use undocumented APIs.
> >
> > > I worry that deciding to go with v3 it going to prevent any forward
> progress
> >
> > Instead of worrying about v3, I think we should just make v2 the default
> to drive up adoption and fix it as we go along. APIs will never improve if
> no one uses it. And no one will use it if we don't document it properly.
> >
> > > What if we dropped the term “experimental”, because that implies that
> the v2 API might not be actually adopted….
> > +1
> >
> > > What if we say “v1 is the Long Term Supported version of the API, and
> v2 is the evolving to be better and better API, monitor the release notes
> for the changes ;-)"
> >
> > I would rather that we say v1 is old and crappy and we'll drop support
> for it soon. V2 is evolving to be better API, and you're encouraged to use
> it.
> >
> >
> >
> >
> >
> > On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <
> epugh@opensourceconnections.com> wrote:
> >>
> >> While the v2 has been out for a long time, do we actually have evidence
> that it is widely used and has significant code written against it?
> >>
> >> When I look at various components/packages that have been written
> around Solr, I don’t see the v2 API used. For example, Project Blacklight,
> a UI for Solr is solidly on v1.
> >>
> >> I worry that deciding to go with v3 it going to prevent any forward
> progress…. Having gone through the effort to document v2 in the Ref Guide,
> I’m not dying to now go and add a v3 for all the examples ;-(. I’d
> rather just update the v2 in place and celebrate the “9.1 has cleaned up
> the X API, come check out the new support for Y” ;-)
> >>
> >> What if we dropped the term “experimental”, because that implies that
> the v2 API might not be actually adopted….
> >>
> >> What if we say “v1 is the Long Term Supported version of the API, and
> v2 is the evolving to be better and better API, monitor the release notes
> for the changes ;-)"
> >>
> >>
> >>
> >> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
> >>
> >> And I think v1/v2 should be split into their own servlets leveraging
> common code by calling utilities, or composing with other objects rather
> than inheriting and getting in each other's way. I think v2 could change a
> lot so experimental seems appropriate, but unfortunately it's been released
> without that moniker for a long time... we may need to go v3 if we want to
> change things since people will understandably have written code against it.
> >>
> >> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <
> arafalov@gmail.com> wrote:
> >>>
> >>> I felt that V2's lack of support for defaults was a serious
> architectural issue that is hard to just close eyes on.
> >>>
> >>> Regards,
> >>> Alex
> >>>
> >>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
> epugh@opensourceconnections.com> wrote:
> >>>>
> >>>> I’d very much like to see this as well.
> >>>>
> >>>> I’ve been thinking that I would look to migrate the Solr Admin to
> using the v2 API, and I suspect it will identify any number of gaps/areas
> of improvement in the v2 API itself.
> >>>>
> >>>>
> >>>>
> >>>>
> >>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
> wrote:
> >>>>
> >>>> Hi all,
> >>>>
> >>>> I'm starting this thread to highlight a subject that came up in the
> >>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
> >>>> should the v2 API be considered "experimental"?
> >>>>
> >>>> We haven't explicitly called the v2 API experimental up to this point,
> >>>> but I'd argue that in essence it already is. In previous releases it
> >>>> was largely undocumented, had little or no SolrJ support, missed
> >>>> parity with v1 in terms of endpoints and parameters, and wasn't
> >>>> included in test randomization. It's hard to imagine how someone
> >>>> could have been using the v2 API nontrivially in our past releases.
> >>>>
> >>>> Treating v2 as "experimental" just feels much more like calling a
> >>>> "spade" a "spade", and sends a more accurate signal to our users. It
> >>>> would also have practical benefits: experimental code is traditionally
> >>>> free from backcompat guarantees, so an "experimental" designation
> >>>> would remove a big impediment for those improving the v2 API.
> >>>>
> >>>> Knowingly setting backcompat aside is always scary, and of course, we
> >>>> don't have any means to know for sure how many users v2 has today.
> >>>> But if we judge from the few signals we do have, the number must be
> >>>> very small. e.g. The last user-list email that mentions a v2 API path
> >>>> is "Atomic update error with JSON handler" from May of 2018!
> >>>>
> >>>> Potential backcompat breaks might inconvenience that small set of
> >>>> users, but that inconvenience would be vastly outweighed by the
> >>>> benefit to all our users of getting a cleaner, more consistent API out
> >>>> sooner.
> >>>>
> >>>> Anyway, that's my pitch. Would love to hear what people think about
> the idea.
> >>>>
> >>>> Best,
> >>>>
> >>>> Jason
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> >>>> For additional commands, e-mail: dev-help@solr.apache.org
> >>>>
> >>>>
> >>>> _______________________
> >>>> 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.
> >>>>
> >>
> >>
> >> --
> >> http://www.needhamsoftware.com (work)
> >> http://www.the111shift.com (play)
> >>
> >>
> >> _______________________
> >> 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
I'm +1 to ensuring V2 APIs are ready by everyone's definition before 9.0.
Hence I'm +1 to treat it as a blocker. However, if others feel we shouldn't
hold it up, I'll likely not care about V2 APIs for another 2 years (by 10.x
timeframe).
On Thu, 28 Oct, 2021, 2:12 am Ishan Chattopadhyaya, <
ichattopadhyaya@gmail.com> wrote:
> My main concern is if we don't put it out there as front and center and
> hence don't allow users to use it, what motivation does that leave for
> developers to continue working on it? If it is not fully ready, some of us
> don't want it to be out there prominently for users to use it. Hence, if I
> can't ensure my efforts will make it fully ready, what is my motivation to
> work on it? By making it default, we signal to users that this is the
> future and you should try it out. Though, it is experimental at the moment.
> Or, use older one, which will eventually be removed.
>
> On Thu, 28 Oct, 2021, 12:30 am Jason Gerlowski, <ge...@gmail.com>
> wrote:
>
>> > For whatever functionality is exposed via V2 APIs, it is ready.
>>
>> You lose me right around here Ishan. IMO exposing functionality makes
>> a particular V2 API "usable", it doesn't necessarily make it "ready".
>> "Ready" implies some confidence that I personally don't have without
>> our test randomization using v2 APIs, without Solr itself doing some
>> dogfooding in SolrJ and in the Admin UI, etc. Those are the biggest 3
>> gaps that I see personally. For me, "ready" comes down to: would I
>> recommend v2 to a client? And as it stands today with those gaps, I
>> personally wouldn't.
>>
>> > If there are critical gaps in V2, lets treat them as blockers before 9.0
>>
>> I don't relish the idea of holding up a looong awaited major release
>> on v2 API changes that a few volunteers are chipping away at in scant
>> personal time. I understand the rare opportunity that major releases
>> offer in terms of deprecation and code removal, and that it's tempting
>> for that reason. But it just doesn't seem realistic to me with
>> current momentum. Better to let the work progress as devs can do it,
>> than slamming the brakes on 9.0 for who knows how long. If people are
>> terribly bummed that v1-deprecation might miss 9.0, then we can always
>> consider a shorter 9.x dev cycle to get it deprecated and removed for
>> a quick 10.0.
>> ----
>>
>> There's been decent response, so an attempt to summarize:
>>
>> * (So far) everyone seems on board with some sort of designation of
>> v2's "evolving" status. (Jason, Eric, Gus, Ishan, Houston). Though
>> exactly what that should be ("experimental"? "beta"? etc) is
>> uncertain.
>> * (So far) there's broad support for relaxing backcompat (Jason, Eric,
>> Ishan, Houston). Though there was a concern about breaking existing
>> users (Gus).
>> ** An alternate suggestion was made to do a v3 API in order to
>> maintain v2 backcompat (Gus), though this raised concerns about
>> slowing down development or being a step back (Jason, Eric, Ishan)
>> * Mixed discussion on making v2 "default" for 9.0. Some in favor
>> (Ishan), some against (Jason, Houston).
>>
>> (If I've mischaracterized anything here, please correct.)
>>
>> On Wed, Oct 27, 2021 at 1:23 PM Eric Pugh
>> <ep...@opensourceconnections.com> wrote:
>> >
>> > I thought about fixing SOLR-14795 when I documented the v2 apis, and
>> the amount of change and the “ugh, it will be hard to have back
>> compatibility” led me to not trying to move any of the sub tickets forward.
>> >
>> > If the V2 version of the API’s is more open to change, then it would
>> make it easier for me to want to try and pick up some of these tickets.
>> >
>> > I think this is an example of why we might want to rethink what we
>> label v2 API’s ;-). Experimental or otherwise!
>> >
>> > On Oct 27, 2021, at 12:24 PM, Alexandre Rafalovitch <ar...@gmail.com>
>> wrote:
>> >
>> > Hmm,
>> >
>> > My understanding was that V2 Config API is part of the V2 APIs and
>> > relevant discussion, so when the questions about gaps came up, I felt
>> > it was relevant. Perhaps it is less relevant than I thought. I will
>> > let others judge and apologize if I introduced too much noise.
>> >
>> > Regards,
>> > Alex.
>> >
>> > On Wed, 27 Oct 2021 at 12:04, Ishan Chattopadhyaya
>> > <ic...@gmail.com> wrote:
>> >
>> >
>> > Alex, these seem to be issues with config API (and should be solved),
>> while this discussion is about v2 version of all APIs. What is the
>> relevance here?
>> >
>> > On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <
>> arafalov@gmail.com> wrote:
>> >
>> >
>> > I feel that the summary of my umbrella case (SOLR-14795) qualifies for
>> this:
>> >
>> > "
>> > General issues with output being materialized schema:
>> > * parameters have already been resolved and are not indicated
>> > * empty keys may not be output (e.g. dataDir)
>> > * default parameters will be output that are not in solrconfig.xml
>> > "
>> >
>> > This had failed to start the discussion at the time, but I feel that
>> > it should have, as Solr configuration without being able to specify
>> > and propagate the defaults implies a very different workflow.
>> >
>> > On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
>> > <ic...@gmail.com> wrote:
>> >
>> >
>> > some aspects of the v2 API are clearly downgrades from the v1 API.
>> >
>> >
>> > Please open a JIRA, and we can discuss there. If there's already any
>> discussion, please point to them.
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > _______________________
>> > 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: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
>>
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
My main concern is if we don't put it out there as front and center and
hence don't allow users to use it, what motivation does that leave for
developers to continue working on it? If it is not fully ready, some of us
don't want it to be out there prominently for users to use it. Hence, if I
can't ensure my efforts will make it fully ready, what is my motivation to
work on it? By making it default, we signal to users that this is the
future and you should try it out. Though, it is experimental at the moment.
Or, use older one, which will eventually be removed.
On Thu, 28 Oct, 2021, 12:30 am Jason Gerlowski, <ge...@gmail.com>
wrote:
> > For whatever functionality is exposed via V2 APIs, it is ready.
>
> You lose me right around here Ishan. IMO exposing functionality makes
> a particular V2 API "usable", it doesn't necessarily make it "ready".
> "Ready" implies some confidence that I personally don't have without
> our test randomization using v2 APIs, without Solr itself doing some
> dogfooding in SolrJ and in the Admin UI, etc. Those are the biggest 3
> gaps that I see personally. For me, "ready" comes down to: would I
> recommend v2 to a client? And as it stands today with those gaps, I
> personally wouldn't.
>
> > If there are critical gaps in V2, lets treat them as blockers before 9.0
>
> I don't relish the idea of holding up a looong awaited major release
> on v2 API changes that a few volunteers are chipping away at in scant
> personal time. I understand the rare opportunity that major releases
> offer in terms of deprecation and code removal, and that it's tempting
> for that reason. But it just doesn't seem realistic to me with
> current momentum. Better to let the work progress as devs can do it,
> than slamming the brakes on 9.0 for who knows how long. If people are
> terribly bummed that v1-deprecation might miss 9.0, then we can always
> consider a shorter 9.x dev cycle to get it deprecated and removed for
> a quick 10.0.
> ----
>
> There's been decent response, so an attempt to summarize:
>
> * (So far) everyone seems on board with some sort of designation of
> v2's "evolving" status. (Jason, Eric, Gus, Ishan, Houston). Though
> exactly what that should be ("experimental"? "beta"? etc) is
> uncertain.
> * (So far) there's broad support for relaxing backcompat (Jason, Eric,
> Ishan, Houston). Though there was a concern about breaking existing
> users (Gus).
> ** An alternate suggestion was made to do a v3 API in order to
> maintain v2 backcompat (Gus), though this raised concerns about
> slowing down development or being a step back (Jason, Eric, Ishan)
> * Mixed discussion on making v2 "default" for 9.0. Some in favor
> (Ishan), some against (Jason, Houston).
>
> (If I've mischaracterized anything here, please correct.)
>
> On Wed, Oct 27, 2021 at 1:23 PM Eric Pugh
> <ep...@opensourceconnections.com> wrote:
> >
> > I thought about fixing SOLR-14795 when I documented the v2 apis, and the
> amount of change and the “ugh, it will be hard to have back compatibility”
> led me to not trying to move any of the sub tickets forward.
> >
> > If the V2 version of the API’s is more open to change, then it would
> make it easier for me to want to try and pick up some of these tickets.
> >
> > I think this is an example of why we might want to rethink what we label
> v2 API’s ;-). Experimental or otherwise!
> >
> > On Oct 27, 2021, at 12:24 PM, Alexandre Rafalovitch <ar...@gmail.com>
> wrote:
> >
> > Hmm,
> >
> > My understanding was that V2 Config API is part of the V2 APIs and
> > relevant discussion, so when the questions about gaps came up, I felt
> > it was relevant. Perhaps it is less relevant than I thought. I will
> > let others judge and apologize if I introduced too much noise.
> >
> > Regards,
> > Alex.
> >
> > On Wed, 27 Oct 2021 at 12:04, Ishan Chattopadhyaya
> > <ic...@gmail.com> wrote:
> >
> >
> > Alex, these seem to be issues with config API (and should be solved),
> while this discussion is about v2 version of all APIs. What is the
> relevance here?
> >
> > On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <ar...@gmail.com>
> wrote:
> >
> >
> > I feel that the summary of my umbrella case (SOLR-14795) qualifies for
> this:
> >
> > "
> > General issues with output being materialized schema:
> > * parameters have already been resolved and are not indicated
> > * empty keys may not be output (e.g. dataDir)
> > * default parameters will be output that are not in solrconfig.xml
> > "
> >
> > This had failed to start the discussion at the time, but I feel that
> > it should have, as Solr configuration without being able to specify
> > and propagate the defaults implies a very different workflow.
> >
> > On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
> > <ic...@gmail.com> wrote:
> >
> >
> > some aspects of the v2 API are clearly downgrades from the v1 API.
> >
> >
> > Please open a JIRA, and we can discuss there. If there's already any
> discussion, please point to them.
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
> >
> > _______________________
> > 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
Re: Should v2 API be "experimental"
Posted by Jan Høydahl <ja...@cominvent.com>.
Agree on this, I wouldn't be surprised if there is a JIRA for it already, have you checked? Pass-through params are quite useful, so we could provide a special prefix 'x.' that would still be allowed, e.g. "x.myCustom=foo"
Jan
> 12. nov. 2021 kl. 00:06 skrev Shawn Heisey <ap...@elyograg.org>:
>
> On 11/4/2021 4:42 PM, Shawn Heisey wrote:
>> This is possibly a pipe dream:
>
> Most of us are probably already aware that the original API ignores unknown parameters sent in with a request. Some of our users utilize this for log parsing -- by including some custom parameter on the request that Solr ignores, they can easily locate requests they are looking for in solr.log.
>
> An interesting problem came up on the #solr slack channel. Solr was silently ignoring the user's request to return facets. Eventually that user figured out that they had unknowingly disabled the facet component on the request handler as they were working on the config.
>
> I think Solr should have the ability, at least on the v2 api, to throw an error when a parameter is not consumed and used by one of the handler's components. An option with a name something like "strictParameterValidation". That option should probably default to disabled in current releases and 9.x, and then if it makes sense, we could possibly choose to enable it by default in a later major release like 10.0.
>
> Thanks,
> Shawn
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Shawn Heisey <ap...@elyograg.org>.
On 11/4/2021 4:42 PM, Shawn Heisey wrote:
> This is possibly a pipe dream:
Most of us are probably already aware that the original API ignores
unknown parameters sent in with a request. Some of our users utilize
this for log parsing -- by including some custom parameter on the
request that Solr ignores, they can easily locate requests they are
looking for in solr.log.
An interesting problem came up on the #solr slack channel. Solr was
silently ignoring the user's request to return facets. Eventually that
user figured out that they had unknowingly disabled the facet component
on the request handler as they were working on the config.
I think Solr should have the ability, at least on the v2 api, to throw
an error when a parameter is not consumed and used by one of the
handler's components. An option with a name something like
"strictParameterValidation". That option should probably default to
disabled in current releases and 9.x, and then if it makes sense, we
could possibly choose to enable it by default in a later major release
like 10.0.
Thanks,
Shawn
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Jan Høydahl <ja...@cominvent.com>.
+1
8x will be in bugfix-only mode after the 8.11 release, so v2 bugfixes are ok, but feel free to innovate and break back-compat in 9.x!
Jan
> 8. nov. 2021 kl. 13:39 skrev Eric Pugh <ep...@opensourceconnections.com>:
>
> Jason G and I were chatting about if we need to back port to the 8X line every change made to enhance the V2 APIs, and my thought was that part of the “experimental” tag is that we could just work in the main code base. This would make it easier to move quicker and not always have that “how is this going to work in in 8X” question in the back of our minds...
>
> If we get to a point where we feel good about the API and want to do a back port to some future 8X release we could, but that we shouldn’t feel constrained to do that for every small improvement to every API.
>
> Thoughts?
>
>
>
>> On Nov 5, 2021, at 9:27 AM, Gus Heck <gus.heck@gmail.com <ma...@gmail.com>> wrote:
>>
>> Once I get the core-container split out into it's own provider/service/whatever started by a context listener, we should do v3 as a servlet giving us a clean slate, and easy access to verbs. I suspect v2 was made much more difficult by the fact that it had to co-exist with a lot of other code inside a filter.
>>
>> On Fri, Nov 5, 2021 at 6:04 AM Jan Høydahl <jan.asf@cominvent.com <ma...@cominvent.com>> wrote:
>> +1 to experimental
>>
>> If we want to be more standards-based, embrace OpenAPI and perhaps more standardized RBAC frameworks, then I believe there will be a v3 API based on JAX-RS or something, with more active use of http verbs.
>> While v2 is harder for devs to use and remember, it has somewhat better practices wrt no mutating state with GET requests, which is the worst thing about v1 imo.
>>
>> Even a v2 or v3 API can have some "convenience" things built-in. I.e. allowing common operations with a simple URL param rather than having to add a POST body for all.
>>
>> Jan
>>
>>> 5. nov. 2021 kl. 10:54 skrev Eric Pugh <epugh@opensourceconnections.com <ma...@opensourceconnections.com>>:
>>>
>>> I can live with “experimental” ;-)
>>>
>>>> On Nov 4, 2021, at 6:42 PM, Shawn Heisey <apache@elyograg.org <ma...@elyograg.org>> wrote:
>>>>
>>>> On 11/4/21 1:20 PM, Jason Gerlowski wrote:
>>>>> 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.
>>>>
>>>> From what I have seen, an experimental designation is the right way to go for v2. If we don't do that, then I think we have to cease development on v2 and create something like v3, designating THAT as experimental. I don't see much value in coming up with a synonym that means the same thing.
>>>>
>>>>> 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.
>>>>
>>>>
>>>> Also from what I have seen, v2 is not ready for adoption yet, so I think we call it experimental and get ready to really overhaul it. I believe I heard somebody say it's incomplete compared to the original API, plus the community has a lot of ideas about major additions and/or fundamental changes in its design. If we eat our own dog food by using the v2 API in things like SolrJ, scripts, and the admin UI, we are more likely to try and come up with stable designs that don't need to be thrown out frequently. The experimental designation would make it possible for us to throw something out and begin again if we find that the existing design of that component is too limiting.
>>>>
>>>> I would like to eventually (in 10.0, maybe) get to a point where we declare the original API as deprecated and remove the experimental designation from v2. At that point we only make new bells and whistles available in v2 ... and then a major version or two after that, we remove the old API entirely. Backward compatibility is an important goal to strive for, but it can't be maintained forever.
>>>>
>>>> This is possibly a pipe dream: I would like a new API to be able to do as much as possible with URL parameters, only REQUIRING a body on the request for things that are complex, or where a body is a natural pathway, like indexing. Of course it should also be possible to put EVERYTHING into the body and send no URL parameters at all. I think they call this wanting to have my cake and eat it too. :) Like I said ... might be a pipe dream.
>>>>
>>>> Something I have found to be invaluable is the fact that a LOT of things can be done and tested with the original API simply by typing a URL into a browser. If everything MUST be done with a request body, I would find that to be extremely inconvenient. If the community thinks that's the right thing to do, then I will adapt. It's not all that difficult to send a body with something like curl. And that requirement might make people more cautious about how they interact with Solr.
>>>>
>>>> Thanks,
>>>> Shawn
>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org <ma...@solr.apache.org>
>>>> For additional commands, e-mail: dev-help@solr.apache.org <ma...@solr.apache.org>
>>>>
>>>
>>> _______________________
>>> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
>>> 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.
>>>
>>
>>
>>
>> --
>> http://www.needhamsoftware.com <http://www.needhamsoftware.com/> (work)
>> http://www.the111shift.com <http://www.the111shift.com/> (play)
>
> _______________________
> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
Jason G and I were chatting about if we need to back port to the 8X line every change made to enhance the V2 APIs, and my thought was that part of the “experimental” tag is that we could just work in the main code base. This would make it easier to move quicker and not always have that “how is this going to work in in 8X” question in the back of our minds...
If we get to a point where we feel good about the API and want to do a back port to some future 8X release we could, but that we shouldn’t feel constrained to do that for every small improvement to every API.
Thoughts?
> On Nov 5, 2021, at 9:27 AM, Gus Heck <gu...@gmail.com> wrote:
>
> Once I get the core-container split out into it's own provider/service/whatever started by a context listener, we should do v3 as a servlet giving us a clean slate, and easy access to verbs. I suspect v2 was made much more difficult by the fact that it had to co-exist with a lot of other code inside a filter.
>
> On Fri, Nov 5, 2021 at 6:04 AM Jan Høydahl <jan.asf@cominvent.com <ma...@cominvent.com>> wrote:
> +1 to experimental
>
> If we want to be more standards-based, embrace OpenAPI and perhaps more standardized RBAC frameworks, then I believe there will be a v3 API based on JAX-RS or something, with more active use of http verbs.
> While v2 is harder for devs to use and remember, it has somewhat better practices wrt no mutating state with GET requests, which is the worst thing about v1 imo.
>
> Even a v2 or v3 API can have some "convenience" things built-in. I.e. allowing common operations with a simple URL param rather than having to add a POST body for all.
>
> Jan
>
>> 5. nov. 2021 kl. 10:54 skrev Eric Pugh <epugh@opensourceconnections.com <ma...@opensourceconnections.com>>:
>>
>> I can live with “experimental” ;-)
>>
>>> On Nov 4, 2021, at 6:42 PM, Shawn Heisey <apache@elyograg.org <ma...@elyograg.org>> wrote:
>>>
>>> On 11/4/21 1:20 PM, Jason Gerlowski wrote:
>>>> 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.
>>>
>>> From what I have seen, an experimental designation is the right way to go for v2. If we don't do that, then I think we have to cease development on v2 and create something like v3, designating THAT as experimental. I don't see much value in coming up with a synonym that means the same thing.
>>>
>>>> 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.
>>>
>>>
>>> Also from what I have seen, v2 is not ready for adoption yet, so I think we call it experimental and get ready to really overhaul it. I believe I heard somebody say it's incomplete compared to the original API, plus the community has a lot of ideas about major additions and/or fundamental changes in its design. If we eat our own dog food by using the v2 API in things like SolrJ, scripts, and the admin UI, we are more likely to try and come up with stable designs that don't need to be thrown out frequently. The experimental designation would make it possible for us to throw something out and begin again if we find that the existing design of that component is too limiting.
>>>
>>> I would like to eventually (in 10.0, maybe) get to a point where we declare the original API as deprecated and remove the experimental designation from v2. At that point we only make new bells and whistles available in v2 ... and then a major version or two after that, we remove the old API entirely. Backward compatibility is an important goal to strive for, but it can't be maintained forever.
>>>
>>> This is possibly a pipe dream: I would like a new API to be able to do as much as possible with URL parameters, only REQUIRING a body on the request for things that are complex, or where a body is a natural pathway, like indexing. Of course it should also be possible to put EVERYTHING into the body and send no URL parameters at all. I think they call this wanting to have my cake and eat it too. :) Like I said ... might be a pipe dream.
>>>
>>> Something I have found to be invaluable is the fact that a LOT of things can be done and tested with the original API simply by typing a URL into a browser. If everything MUST be done with a request body, I would find that to be extremely inconvenient. If the community thinks that's the right thing to do, then I will adapt. It's not all that difficult to send a body with something like curl. And that requirement might make people more cautious about how they interact with Solr.
>>>
>>> Thanks,
>>> Shawn
>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org <ma...@solr.apache.org>
>>> For additional commands, e-mail: dev-help@solr.apache.org <ma...@solr.apache.org>
>>>
>>
>> _______________________
>> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
>> 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.
>>
>
>
>
> --
> http://www.needhamsoftware.com <http://www.needhamsoftware.com/> (work)
> http://www.the111shift.com <http://www.the111shift.com/> (play)
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.
Re: Should v2 API be "experimental"
Posted by Gus Heck <gu...@gmail.com>.
Once I get the core-container split out into it's own
provider/service/whatever started by a context listener, we should do v3 as
a servlet giving us a clean slate, and easy access to verbs. I suspect v2
was made much more difficult by the fact that it had to co-exist with a lot
of other code inside a filter.
On Fri, Nov 5, 2021 at 6:04 AM Jan Høydahl <ja...@cominvent.com> wrote:
> +1 to experimental
>
> If we want to be more standards-based, embrace OpenAPI and perhaps more
> standardized RBAC frameworks, then I believe there will be a v3 API based
> on JAX-RS or something, with more active use of http verbs.
> While v2 is harder for devs to use and remember, it has somewhat better
> practices wrt no mutating state with GET requests, which is the worst thing
> about v1 imo.
>
> Even a v2 or v3 API can have some "convenience" things built-in. I.e.
> allowing common operations with a simple URL param rather than having to
> add a POST body for all.
>
> Jan
>
> 5. nov. 2021 kl. 10:54 skrev Eric Pugh <ep...@opensourceconnections.com>:
>
> I can live with “experimental” ;-)
>
> On Nov 4, 2021, at 6:42 PM, Shawn Heisey <ap...@elyograg.org> wrote:
>
> On 11/4/21 1:20 PM, Jason Gerlowski wrote:
>
> 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.
>
>
> From what I have seen, an experimental designation is the right way to go
> for v2. If we don't do that, then I think we have to cease development on
> v2 and create something like v3, designating THAT as experimental. I don't
> see much value in coming up with a synonym that means the same thing.
>
> 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.
>
>
>
> Also from what I have seen, v2 is not ready for adoption yet, so I think
> we call it experimental and get ready to really overhaul it. I believe I
> heard somebody say it's incomplete compared to the original API, plus the
> community has a lot of ideas about major additions and/or fundamental
> changes in its design. If we eat our own dog food by using the v2 API in
> things like SolrJ, scripts, and the admin UI, we are more likely to try and
> come up with stable designs that don't need to be thrown out frequently.
> The experimental designation would make it possible for us to throw
> something out and begin again if we find that the existing design of that
> component is too limiting.
>
> I would like to eventually (in 10.0, maybe) get to a point where we
> declare the original API as deprecated and remove the experimental
> designation from v2. At that point we only make new bells and whistles
> available in v2 ... and then a major version or two after that, we remove
> the old API entirely. Backward compatibility is an important goal to strive
> for, but it can't be maintained forever.
>
> This is possibly a pipe dream: I would like a new API to be able to do as
> much as possible with URL parameters, only REQUIRING a body on the request
> for things that are complex, or where a body is a natural pathway, like
> indexing. Of course it should also be possible to put EVERYTHING into the
> body and send no URL parameters at all. I think they call this wanting to
> have my cake and eat it too. :) Like I said ... might be a pipe dream.
>
> Something I have found to be invaluable is the fact that a LOT of things
> can be done and tested with the original API simply by typing a URL into a
> browser. If everything MUST be done with a request body, I would find that
> to be extremely inconvenient. If the community thinks that's the right
> thing to do, then I will adapt. It's not all that difficult to send a body
> with something like curl. And that requirement might make people more
> cautious about how they interact with Solr.
>
> Thanks,
> Shawn
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> <de...@solr.apache.org>
> For additional commands, e-mail: dev-help@solr.apache.org
> <de...@solr.apache.org>
>
>
> _______________________
> *Eric Pugh **| *Founder & CEO | OpenSource Connections, LLC | 434.466.1467
> | http://www.opensourceconnections.com | My Free/Busy
> <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
> <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Should v2 API be "experimental"
Posted by Jan Høydahl <ja...@cominvent.com>.
+1 to experimental
If we want to be more standards-based, embrace OpenAPI and perhaps more standardized RBAC frameworks, then I believe there will be a v3 API based on JAX-RS or something, with more active use of http verbs.
While v2 is harder for devs to use and remember, it has somewhat better practices wrt no mutating state with GET requests, which is the worst thing about v1 imo.
Even a v2 or v3 API can have some "convenience" things built-in. I.e. allowing common operations with a simple URL param rather than having to add a POST body for all.
Jan
> 5. nov. 2021 kl. 10:54 skrev Eric Pugh <ep...@opensourceconnections.com>:
>
> I can live with “experimental” ;-)
>
>> On Nov 4, 2021, at 6:42 PM, Shawn Heisey <apache@elyograg.org <ma...@elyograg.org>> wrote:
>>
>> On 11/4/21 1:20 PM, Jason Gerlowski wrote:
>>> 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.
>>
>> From what I have seen, an experimental designation is the right way to go for v2. If we don't do that, then I think we have to cease development on v2 and create something like v3, designating THAT as experimental. I don't see much value in coming up with a synonym that means the same thing.
>>
>>> 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.
>>
>>
>> Also from what I have seen, v2 is not ready for adoption yet, so I think we call it experimental and get ready to really overhaul it. I believe I heard somebody say it's incomplete compared to the original API, plus the community has a lot of ideas about major additions and/or fundamental changes in its design. If we eat our own dog food by using the v2 API in things like SolrJ, scripts, and the admin UI, we are more likely to try and come up with stable designs that don't need to be thrown out frequently. The experimental designation would make it possible for us to throw something out and begin again if we find that the existing design of that component is too limiting.
>>
>> I would like to eventually (in 10.0, maybe) get to a point where we declare the original API as deprecated and remove the experimental designation from v2. At that point we only make new bells and whistles available in v2 ... and then a major version or two after that, we remove the old API entirely. Backward compatibility is an important goal to strive for, but it can't be maintained forever.
>>
>> This is possibly a pipe dream: I would like a new API to be able to do as much as possible with URL parameters, only REQUIRING a body on the request for things that are complex, or where a body is a natural pathway, like indexing. Of course it should also be possible to put EVERYTHING into the body and send no URL parameters at all. I think they call this wanting to have my cake and eat it too. :) Like I said ... might be a pipe dream.
>>
>> Something I have found to be invaluable is the fact that a LOT of things can be done and tested with the original API simply by typing a URL into a browser. If everything MUST be done with a request body, I would find that to be extremely inconvenient. If the community thinks that's the right thing to do, then I will adapt. It's not all that difficult to send a body with something like curl. And that requirement might make people more cautious about how they interact with Solr.
>>
>> Thanks,
>> Shawn
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org <ma...@solr.apache.org>
>> For additional commands, e-mail: dev-help@solr.apache.org <ma...@solr.apache.org>
>>
>
> _______________________
> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
I can live with “experimental” ;-)
> On Nov 4, 2021, at 6:42 PM, Shawn Heisey <ap...@elyograg.org> wrote:
>
> On 11/4/21 1:20 PM, Jason Gerlowski wrote:
>> 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.
>
> From what I have seen, an experimental designation is the right way to go for v2. If we don't do that, then I think we have to cease development on v2 and create something like v3, designating THAT as experimental. I don't see much value in coming up with a synonym that means the same thing.
>
>> 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.
>
>
> Also from what I have seen, v2 is not ready for adoption yet, so I think we call it experimental and get ready to really overhaul it. I believe I heard somebody say it's incomplete compared to the original API, plus the community has a lot of ideas about major additions and/or fundamental changes in its design. If we eat our own dog food by using the v2 API in things like SolrJ, scripts, and the admin UI, we are more likely to try and come up with stable designs that don't need to be thrown out frequently. The experimental designation would make it possible for us to throw something out and begin again if we find that the existing design of that component is too limiting.
>
> I would like to eventually (in 10.0, maybe) get to a point where we declare the original API as deprecated and remove the experimental designation from v2. At that point we only make new bells and whistles available in v2 ... and then a major version or two after that, we remove the old API entirely. Backward compatibility is an important goal to strive for, but it can't be maintained forever.
>
> This is possibly a pipe dream: I would like a new API to be able to do as much as possible with URL parameters, only REQUIRING a body on the request for things that are complex, or where a body is a natural pathway, like indexing. Of course it should also be possible to put EVERYTHING into the body and send no URL parameters at all. I think they call this wanting to have my cake and eat it too. :) Like I said ... might be a pipe dream.
>
> Something I have found to be invaluable is the fact that a LOT of things can be done and tested with the original API simply by typing a URL into a browser. If everything MUST be done with a request body, I would find that to be extremely inconvenient. If the community thinks that's the right thing to do, then I will adapt. It's not all that difficult to send a body with something like curl. And that requirement might make people more cautious about how they interact with Solr.
>
> Thanks,
> Shawn
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.
Re: Should v2 API be "experimental"
Posted by Shawn Heisey <ap...@elyograg.org>.
On 11/4/21 1:20 PM, Jason Gerlowski wrote:
> 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.
From what I have seen, an experimental designation is the right way to
go for v2. If we don't do that, then I think we have to cease
development on v2 and create something like v3, designating THAT as
experimental. I don't see much value in coming up with a synonym that
means the same thing.
> 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.
Also from what I have seen, v2 is not ready for adoption yet, so I think
we call it experimental and get ready to really overhaul it. I believe
I heard somebody say it's incomplete compared to the original API, plus
the community has a lot of ideas about major additions and/or
fundamental changes in its design. If we eat our own dog food by using
the v2 API in things like SolrJ, scripts, and the admin UI, we are more
likely to try and come up with stable designs that don't need to be
thrown out frequently. The experimental designation would make it
possible for us to throw something out and begin again if we find that
the existing design of that component is too limiting.
I would like to eventually (in 10.0, maybe) get to a point where we
declare the original API as deprecated and remove the experimental
designation from v2. At that point we only make new bells and whistles
available in v2 ... and then a major version or two after that, we
remove the old API entirely. Backward compatibility is an important goal
to strive for, but it can't be maintained forever.
This is possibly a pipe dream: I would like a new API to be able to do
as much as possible with URL parameters, only REQUIRING a body on the
request for things that are complex, or where a body is a natural
pathway, like indexing. Of course it should also be possible to put
EVERYTHING into the body and send no URL parameters at all. I think
they call this wanting to have my cake and eat it too. :) Like I said
... might be a pipe dream.
Something I have found to be invaluable is the fact that a LOT of things
can be done and tested with the original API simply by typing a URL into
a browser. If everything MUST be done with a request body, I would find
that to be extremely inconvenient. If the community thinks that's the
right thing to do, then I will adapt. It's not all that difficult to
send a body with something like curl. And that requirement might make
people more cautious about how they interact with Solr.
Thanks,
Shawn
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Gus Heck <gu...@gmail.com>.
I raised the point as a general concern but I'm quite willing to accept the
clear majority opinion. Definitely not anywhere near veto :)
On Thu, Nov 4, 2021 at 3:20 PM Jason Gerlowski <ge...@gmail.com>
wrote:
> 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 <th...@gmail.com>
> 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 <ge...@gmail.com>
> 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 <ja...@cominvent.com>
> 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 <
> houstonputman@gmail.com>:
> > > >
> > > >
> > > > I'm definitely +1 on the OpenAPI requirement for v2 going forward.
> > > >
> > > > On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <
> thelabdude@gmail.com> 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
> > > >> <ep...@opensourceconnections.com> 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 <
> thelabdude@gmail.com> 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 <
> jan.asf@cominvent.com> 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 <ds...@apache.org>:
> > > >> >
> > > >> >
> > > >> > 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: dev-unsubscribe@solr.apache.org
> > > >> > For additional commands, e-mail: dev-help@solr.apache.org
> > > >> >
> > > >> >
> > > >> >
> ---------------------------------------------------------------------
> > > >> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > > >> > For additional commands, e-mail: dev-help@solr.apache.org
> > > >> >
> > > >> >
> > > >> > _______________________
> > > >> > 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: dev-unsubscribe@solr.apache.org
> > > >> For additional commands, e-mail: dev-help@solr.apache.org
> > > >>
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > > For additional commands, e-mail: dev-help@solr.apache.org
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Should v2 API be "experimental"
Posted by Jason Gerlowski <ge...@gmail.com>.
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 <th...@gmail.com> 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 <ge...@gmail.com> 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 <ja...@cominvent.com> 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 <ho...@gmail.com>:
> > >
> > >
> > > I'm definitely +1 on the OpenAPI requirement for v2 going forward.
> > >
> > > On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <th...@gmail.com> 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
> > >> <ep...@opensourceconnections.com> 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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
> > >> >
> > >> >
> > >> > 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: dev-unsubscribe@solr.apache.org
> > >> > For additional commands, e-mail: dev-help@solr.apache.org
> > >> >
> > >> >
> > >> > ---------------------------------------------------------------------
> > >> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > >> > For additional commands, e-mail: dev-help@solr.apache.org
> > >> >
> > >> >
> > >> > _______________________
> > >> > 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: dev-unsubscribe@solr.apache.org
> > >> For additional commands, e-mail: dev-help@solr.apache.org
> > >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Timothy Potter <th...@gmail.com>.
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 <ge...@gmail.com> 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 <ja...@cominvent.com> 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 <ho...@gmail.com>:
> >
> >
> > I'm definitely +1 on the OpenAPI requirement for v2 going forward.
> >
> > On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <th...@gmail.com> 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
> >> <ep...@opensourceconnections.com> 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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
> >> >
> >> >
> >> > 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: dev-unsubscribe@solr.apache.org
> >> > For additional commands, e-mail: dev-help@solr.apache.org
> >> >
> >> >
> >> > ---------------------------------------------------------------------
> >> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> >> > For additional commands, e-mail: dev-help@solr.apache.org
> >> >
> >> >
> >> > _______________________
> >> > 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: dev-unsubscribe@solr.apache.org
> >> For additional commands, e-mail: dev-help@solr.apache.org
> >>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Jason Gerlowski <ge...@gmail.com>.
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 <ja...@cominvent.com> 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 <ho...@gmail.com>:
>
>
> I'm definitely +1 on the OpenAPI requirement for v2 going forward.
>
> On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <th...@gmail.com> 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
>> <ep...@opensourceconnections.com> 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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
>> >
>> >
>> > 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: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > _______________________
>> > 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: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Jan Høydahl <ja...@cominvent.com>.
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 <ho...@gmail.com>:
>
>
> I'm definitely +1 on the OpenAPI requirement for v2 going forward.
>
>> On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <th...@gmail.com> 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
>> <ep...@opensourceconnections.com> 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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
>> >
>> >
>> > 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: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> > For additional commands, e-mail: dev-help@solr.apache.org
>> >
>> >
>> > _______________________
>> > 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: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
Re: Should v2 API be "experimental"
Posted by Houston Putman <ho...@gmail.com>.
I'm definitely +1 on the OpenAPI requirement for v2 going forward.
On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter <th...@gmail.com>
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
> <ep...@opensourceconnections.com> 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 <th...@gmail.com>
> 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 <ja...@cominvent.com>
> 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 <ds...@apache.org>:
> >
> >
> > 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: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
> >
> > _______________________
> > 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
Re: Should v2 API be "experimental"
Posted by Timothy Potter <th...@gmail.com>.
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
<ep...@opensourceconnections.com> 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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
>
>
> 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
> _______________________
> 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: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
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 <th...@gmail.com> 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 <ja...@cominvent.com> 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 <ds...@apache.org>:
>>>
>>>
>>> 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: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.
Re: Should v2 API be "experimental"
Posted by Timothy Potter <th...@gmail.com>.
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 <ja...@cominvent.com> 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 <ds...@apache.org>:
> >
> >
> > 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Jan Høydahl <ja...@cominvent.com>.
+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 <ds...@apache.org>:
>
>
> 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: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by David Smiley <ds...@apache.org>.
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).
Re: Should v2 API be "experimental"
Posted by Jason Gerlowski <ge...@gmail.com>.
> For whatever functionality is exposed via V2 APIs, it is ready.
You lose me right around here Ishan. IMO exposing functionality makes
a particular V2 API "usable", it doesn't necessarily make it "ready".
"Ready" implies some confidence that I personally don't have without
our test randomization using v2 APIs, without Solr itself doing some
dogfooding in SolrJ and in the Admin UI, etc. Those are the biggest 3
gaps that I see personally. For me, "ready" comes down to: would I
recommend v2 to a client? And as it stands today with those gaps, I
personally wouldn't.
> If there are critical gaps in V2, lets treat them as blockers before 9.0
I don't relish the idea of holding up a looong awaited major release
on v2 API changes that a few volunteers are chipping away at in scant
personal time. I understand the rare opportunity that major releases
offer in terms of deprecation and code removal, and that it's tempting
for that reason. But it just doesn't seem realistic to me with
current momentum. Better to let the work progress as devs can do it,
than slamming the brakes on 9.0 for who knows how long. If people are
terribly bummed that v1-deprecation might miss 9.0, then we can always
consider a shorter 9.x dev cycle to get it deprecated and removed for
a quick 10.0.
----
There's been decent response, so an attempt to summarize:
* (So far) everyone seems on board with some sort of designation of
v2's "evolving" status. (Jason, Eric, Gus, Ishan, Houston). Though
exactly what that should be ("experimental"? "beta"? etc) is
uncertain.
* (So far) there's broad support for relaxing backcompat (Jason, Eric,
Ishan, Houston). Though there was a concern about breaking existing
users (Gus).
** An alternate suggestion was made to do a v3 API in order to
maintain v2 backcompat (Gus), though this raised concerns about
slowing down development or being a step back (Jason, Eric, Ishan)
* Mixed discussion on making v2 "default" for 9.0. Some in favor
(Ishan), some against (Jason, Houston).
(If I've mischaracterized anything here, please correct.)
On Wed, Oct 27, 2021 at 1:23 PM Eric Pugh
<ep...@opensourceconnections.com> wrote:
>
> I thought about fixing SOLR-14795 when I documented the v2 apis, and the amount of change and the “ugh, it will be hard to have back compatibility” led me to not trying to move any of the sub tickets forward.
>
> If the V2 version of the API’s is more open to change, then it would make it easier for me to want to try and pick up some of these tickets.
>
> I think this is an example of why we might want to rethink what we label v2 API’s ;-). Experimental or otherwise!
>
> On Oct 27, 2021, at 12:24 PM, Alexandre Rafalovitch <ar...@gmail.com> wrote:
>
> Hmm,
>
> My understanding was that V2 Config API is part of the V2 APIs and
> relevant discussion, so when the questions about gaps came up, I felt
> it was relevant. Perhaps it is less relevant than I thought. I will
> let others judge and apologize if I introduced too much noise.
>
> Regards,
> Alex.
>
> On Wed, 27 Oct 2021 at 12:04, Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
>
>
> Alex, these seem to be issues with config API (and should be solved), while this discussion is about v2 version of all APIs. What is the relevance here?
>
> On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <ar...@gmail.com> wrote:
>
>
> I feel that the summary of my umbrella case (SOLR-14795) qualifies for this:
>
> "
> General issues with output being materialized schema:
> * parameters have already been resolved and are not indicated
> * empty keys may not be output (e.g. dataDir)
> * default parameters will be output that are not in solrconfig.xml
> "
>
> This had failed to start the discussion at the time, but I feel that
> it should have, as Solr configuration without being able to specify
> and propagate the defaults implies a very different workflow.
>
> On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
>
>
> some aspects of the v2 API are clearly downgrades from the v1 API.
>
>
> Please open a JIRA, and we can discuss there. If there's already any discussion, please point to them.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
> _______________________
> 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: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
I thought about fixing SOLR-14795 when I documented the v2 apis, and the amount of change and the “ugh, it will be hard to have back compatibility” led me to not trying to move any of the sub tickets forward.
If the V2 version of the API’s is more open to change, then it would make it easier for me to want to try and pick up some of these tickets.
I think this is an example of why we might want to rethink what we label v2 API’s ;-). Experimental or otherwise!
> On Oct 27, 2021, at 12:24 PM, Alexandre Rafalovitch <ar...@gmail.com> wrote:
>
> Hmm,
>
> My understanding was that V2 Config API is part of the V2 APIs and
> relevant discussion, so when the questions about gaps came up, I felt
> it was relevant. Perhaps it is less relevant than I thought. I will
> let others judge and apologize if I introduced too much noise.
>
> Regards,
> Alex.
>
> On Wed, 27 Oct 2021 at 12:04, Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
>>
>> Alex, these seem to be issues with config API (and should be solved), while this discussion is about v2 version of all APIs. What is the relevance here?
>>
>> On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <ar...@gmail.com> wrote:
>>>
>>> I feel that the summary of my umbrella case (SOLR-14795) qualifies for this:
>>>
>>> "
>>> General issues with output being materialized schema:
>>> * parameters have already been resolved and are not indicated
>>> * empty keys may not be output (e.g. dataDir)
>>> * default parameters will be output that are not in solrconfig.xml
>>> "
>>>
>>> This had failed to start the discussion at the time, but I feel that
>>> it should have, as Solr configuration without being able to specify
>>> and propagate the defaults implies a very different workflow.
>>>
>>> On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
>>> <ic...@gmail.com> wrote:
>>>>
>>>>> some aspects of the v2 API are clearly downgrades from the v1 API.
>>>>
>>>> Please open a JIRA, and we can discuss there. If there's already any discussion, please point to them.
>>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>>> For additional commands, e-mail: dev-help@solr.apache.org
>>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.
Re: Should v2 API be "experimental"
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
Hmm,
My understanding was that V2 Config API is part of the V2 APIs and
relevant discussion, so when the questions about gaps came up, I felt
it was relevant. Perhaps it is less relevant than I thought. I will
let others judge and apologize if I introduced too much noise.
Regards,
Alex.
On Wed, 27 Oct 2021 at 12:04, Ishan Chattopadhyaya
<ic...@gmail.com> wrote:
>
> Alex, these seem to be issues with config API (and should be solved), while this discussion is about v2 version of all APIs. What is the relevance here?
>
> On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <ar...@gmail.com> wrote:
>>
>> I feel that the summary of my umbrella case (SOLR-14795) qualifies for this:
>>
>> "
>> General issues with output being materialized schema:
>> * parameters have already been resolved and are not indicated
>> * empty keys may not be output (e.g. dataDir)
>> * default parameters will be output that are not in solrconfig.xml
>> "
>>
>> This had failed to start the discussion at the time, but I feel that
>> it should have, as Solr configuration without being able to specify
>> and propagate the defaults implies a very different workflow.
>>
>> On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
>> <ic...@gmail.com> wrote:
>> >
>> > > some aspects of the v2 API are clearly downgrades from the v1 API.
>> >
>> > Please open a JIRA, and we can discuss there. If there's already any discussion, please point to them.
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
Alex, these seem to be issues with config API (and should be solved), while
this discussion is about v2 version of all APIs. What is the relevance here?
On Wed, 27 Oct, 2021, 9:24 pm Alexandre Rafalovitch, <ar...@gmail.com>
wrote:
> I feel that the summary of my umbrella case (SOLR-14795) qualifies for
> this:
>
> "
> General issues with output being materialized schema:
> * parameters have already been resolved and are not indicated
> * empty keys may not be output (e.g. dataDir)
> * default parameters will be output that are not in solrconfig.xml
> "
>
> This had failed to start the discussion at the time, but I feel that
> it should have, as Solr configuration without being able to specify
> and propagate the defaults implies a very different workflow.
>
> On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
> >
> > > some aspects of the v2 API are clearly downgrades from the v1 API.
> >
> > Please open a JIRA, and we can discuss there. If there's already any
> discussion, please point to them.
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
Re: Should v2 API be "experimental"
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
I feel that the summary of my umbrella case (SOLR-14795) qualifies for this:
"
General issues with output being materialized schema:
* parameters have already been resolved and are not indicated
* empty keys may not be output (e.g. dataDir)
* default parameters will be output that are not in solrconfig.xml
"
This had failed to start the discussion at the time, but I feel that
it should have, as Solr configuration without being able to specify
and propagate the defaults implies a very different workflow.
On Wed, 27 Oct 2021 at 11:34, Ishan Chattopadhyaya
<ic...@gmail.com> wrote:
>
> > some aspects of the v2 API are clearly downgrades from the v1 API.
>
> Please open a JIRA, and we can discuss there. If there's already any discussion, please point to them.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
> some aspects of the v2 API are clearly downgrades from the v1 API.
Please open a JIRA, and we can discuss there. If there's already any
discussion, please point to them.
> My big concerns are purely "cosmetic" (HTTP Methods, API paths, HTTP
Status Codes, etc).
Patches welcome. Or if you open a JIRA, we can discuss there.
On Wed, Oct 27, 2021 at 8:57 PM Ishan Chattopadhyaya <
ichattopadhyaya@gmail.com> wrote:
> > While that does mean that users will be hesitant to move to it for the
> time
> > being, isn't that kind of the point since we are planning on changing
> things?
>
> Exactly, that's the point of major release upgrades. Users will remain
> sceptical of moving production to 9x during the early few releases anyway.
> Hopefully, we'll fix the APIs during that phase. Towards that, if APIs
> change a little, that should be alright, in my opinion. We should just do a
> good job of documenting the changes in release notes. We can *start with
> all V2 APIs marked experimental in 9.0 and keep unmarking in subsequent
> minor releases* as parts of it mature.
>
> > Why do we want users to use something when it's not ready.
>
> For whatever functionality is exposed via V2 APIs, it is ready. There may
> be bugs that we'll get to know about only once users start using it. If
> there are critical bugs or gaps that we know of, let us address them now
> before a 9.0 release.
>
> So, here's my thoughts:
> 1) Make V2 the default in 9x, because unless it is the default, no one
> will use it. If users are so scared, they can stay with 8x or use the older
> v1 APIs on 9x.
> 2) If there are critical gaps in V2, lets treat them as blockers before
> 9.0.
> 3) Only 1-2 developers have worked on building these APIs, and just 1-2
> committers have worked on documenting these APIs. Let us join forces
> positively to take this forward and fix all problems (code and
> documentation), since they are an amazing quality of life improvement for
> everyone using these APIs. These APIs make Solr look much better than
> before.
>
>
> On Wed, Oct 27, 2021 at 8:37 PM Houston Putman <ho...@gmail.com>
> wrote:
>
>> Personally I think, while it made a lot of improvements, some aspects of
>> the v2 API are clearly downgrades from the v1 API.
>> I do think we should move towards deprecating the v1 API, but not until
>> we have a solid (and documented of course) v2 or v3 API.
>>
>> Instead of worrying about v3, I think we should just make v2 the default
>>> to drive up adoption and fix it as we go along. APIs will never improve if
>>> no one uses it. And no one will use it if we don't document it properly.
>>>
>>
>> If we make v2 the default, that means we can't go and make necessary
>> backwards-incompatible changes along the way. We need to make those changes
>> first before we go and recommend that people use it.
>>
>> I agree that the v2 API should be "experimental", or whatever phrase we
>> want to use to say that the API might change between minor versions, until
>> it's in a much better shape.
>>
>> While that does mean that users will be hesitant to move to it for the
>> time being, isn't that kind of the point since we are planning on changing
>> things? Why do we want users to use something when it's not ready.
>> I agree that it's harder to improve an API that no one uses, but more
>> importantly (to me) no one will use an API that breaks on them after
>> upgrading a minor version, unless they are explicitly told this can happen.
>>
>> I think there should be some indicator to users about the quality and
>>> guarantees around the v2 API, but I'm not especially attached to
>>> "experimental" if it's disliked.
>>>
>>
>> 100% agreed here. (Wrote my previous paragraphs before your reply)
>>
>> If there were discussions around huge changes...
>>
>>
>> Completely agreed here as well. My big concerns are purely "cosmetic"
>> (HTTP Methods, API paths, HTTP Status Codes, etc). If we want to start
>> using protobuf or something like that, then yes a v3 will be required.
>>
>> - Houston
>>
>> On Wed, Oct 27, 2021 at 11:01 AM Jason Gerlowski <ge...@gmail.com>
>> wrote:
>>
>>> > unfortunately it's been released without that moniker for a long time
>>> ... we may need to go v3 if we want to change things since people will
>>> understandably have written code against it.
>>>
>>> The idea of breaking "existing v2 users" is definitely a sticking
>>> point. But I think there's a strong case that these users are a tiny
>>> tiny minority out there: see the past lack of v2 docs, SolrJ support,
>>> mailing list traffic or bug reports on v2, etc. And if you accept
>>> that, then deciding to rigidly follow backcompat or not comes down to
>>> deciding what offers the community as a whole more benefit:
>>> maintaining API compatibility to avoid code breaks for this tiny
>>> minority, or getting a more polished API over the finish line sooner
>>> for use by all.
>>>
>>> Gus - you're right that we could do a "v3"-type approach here while
>>> maintaining backcompat, but I agree with Eric's point that v3 would be
>>> a step back in terms of forward progress on getting a new API out. If
>>> there were discussions around huge changes (switching to protobuf,
>>> removing commonly used APIs, etc.) that step back would be worth it.
>>> But for the pretty minor backcompat changes that have been proposed
>>> (e.g. renaming params for consistency "configSet" -> "config") - it
>>> just seems like overkill. If we're worried about upsetting users,
>>> there's lots we can do in terms of signaling any potential changes
>>> well in advance via ANNOUNCE emails, ref guide docs, etc.
>>>
>>> > What if we dropped the term “experimental”, because that implies that
>>> the v2 API might not be actually adopted
>>>
>>> I think there should be some indicator to users about the quality and
>>> guarantees around the v2 API, but I'm not especially attached to
>>> "experimental" if it's disliked. That said, maybe we should reach
>>> consensus on some of the other questions (i.e. backcompat
>>> implications) and then figure out what word/label best conveys things.
>>>
>>> Jason
>>>
>>> On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya
>>> <ic...@gmail.com> wrote:
>>> >
>>> > > While the v2 has been out for a long time, do we actually have
>>> evidence that it is widely used and has significant code written against it?
>>> >
>>> > I don't think anyone uses V2 APIs. No one wants to use undocumented
>>> APIs.
>>> >
>>> > > I worry that deciding to go with v3 it going to prevent any forward
>>> progress
>>> >
>>> > Instead of worrying about v3, I think we should just make v2 the
>>> default to drive up adoption and fix it as we go along. APIs will never
>>> improve if no one uses it. And no one will use it if we don't document it
>>> properly.
>>> >
>>> > > What if we dropped the term “experimental”, because that implies
>>> that the v2 API might not be actually adopted….
>>> > +1
>>> >
>>> > > What if we say “v1 is the Long Term Supported version of the API,
>>> and v2 is the evolving to be better and better API, monitor the release
>>> notes for the changes ;-)"
>>> >
>>> > I would rather that we say v1 is old and crappy and we'll drop support
>>> for it soon. V2 is evolving to be better API, and you're encouraged to use
>>> it.
>>> >
>>> >
>>> >
>>> >
>>> >
>>> > On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <
>>> epugh@opensourceconnections.com> wrote:
>>> >>
>>> >> While the v2 has been out for a long time, do we actually have
>>> evidence that it is widely used and has significant code written against it?
>>> >>
>>> >> When I look at various components/packages that have been written
>>> around Solr, I don’t see the v2 API used. For example, Project Blacklight,
>>> a UI for Solr is solidly on v1.
>>> >>
>>> >> I worry that deciding to go with v3 it going to prevent any forward
>>> progress…. Having gone through the effort to document v2 in the Ref Guide,
>>> I’m not dying to now go and add a v3 for all the examples ;-(. I’d
>>> rather just update the v2 in place and celebrate the “9.1 has cleaned up
>>> the X API, come check out the new support for Y” ;-)
>>> >>
>>> >> What if we dropped the term “experimental”, because that implies that
>>> the v2 API might not be actually adopted….
>>> >>
>>> >> What if we say “v1 is the Long Term Supported version of the API, and
>>> v2 is the evolving to be better and better API, monitor the release notes
>>> for the changes ;-)"
>>> >>
>>> >>
>>> >>
>>> >> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
>>> >>
>>> >> And I think v1/v2 should be split into their own servlets leveraging
>>> common code by calling utilities, or composing with other objects rather
>>> than inheriting and getting in each other's way. I think v2 could change a
>>> lot so experimental seems appropriate, but unfortunately it's been released
>>> without that moniker for a long time... we may need to go v3 if we want to
>>> change things since people will understandably have written code against it.
>>> >>
>>> >> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <
>>> arafalov@gmail.com> wrote:
>>> >>>
>>> >>> I felt that V2's lack of support for defaults was a serious
>>> architectural issue that is hard to just close eyes on.
>>> >>>
>>> >>> Regards,
>>> >>> Alex
>>> >>>
>>> >>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
>>> epugh@opensourceconnections.com> wrote:
>>> >>>>
>>> >>>> I’d very much like to see this as well.
>>> >>>>
>>> >>>> I’ve been thinking that I would look to migrate the Solr Admin to
>>> using the v2 API, and I suspect it will identify any number of gaps/areas
>>> of improvement in the v2 API itself.
>>> >>>>
>>> >>>>
>>> >>>>
>>> >>>>
>>> >>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
>>> wrote:
>>> >>>>
>>> >>>> Hi all,
>>> >>>>
>>> >>>> I'm starting this thread to highlight a subject that came up in the
>>> >>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>>> >>>> should the v2 API be considered "experimental"?
>>> >>>>
>>> >>>> We haven't explicitly called the v2 API experimental up to this
>>> point,
>>> >>>> but I'd argue that in essence it already is. In previous releases
>>> it
>>> >>>> was largely undocumented, had little or no SolrJ support, missed
>>> >>>> parity with v1 in terms of endpoints and parameters, and wasn't
>>> >>>> included in test randomization. It's hard to imagine how someone
>>> >>>> could have been using the v2 API nontrivially in our past releases.
>>> >>>>
>>> >>>> Treating v2 as "experimental" just feels much more like calling a
>>> >>>> "spade" a "spade", and sends a more accurate signal to our users.
>>> It
>>> >>>> would also have practical benefits: experimental code is
>>> traditionally
>>> >>>> free from backcompat guarantees, so an "experimental" designation
>>> >>>> would remove a big impediment for those improving the v2 API.
>>> >>>>
>>> >>>> Knowingly setting backcompat aside is always scary, and of course,
>>> we
>>> >>>> don't have any means to know for sure how many users v2 has today.
>>> >>>> But if we judge from the few signals we do have, the number must be
>>> >>>> very small. e.g. The last user-list email that mentions a v2 API
>>> path
>>> >>>> is "Atomic update error with JSON handler" from May of 2018!
>>> >>>>
>>> >>>> Potential backcompat breaks might inconvenience that small set of
>>> >>>> users, but that inconvenience would be vastly outweighed by the
>>> >>>> benefit to all our users of getting a cleaner, more consistent API
>>> out
>>> >>>> sooner.
>>> >>>>
>>> >>>> Anyway, that's my pitch. Would love to hear what people think
>>> about the idea.
>>> >>>>
>>> >>>> Best,
>>> >>>>
>>> >>>> Jason
>>> >>>>
>>> >>>>
>>> ---------------------------------------------------------------------
>>> >>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>>> >>>> For additional commands, e-mail: dev-help@solr.apache.org
>>> >>>>
>>> >>>>
>>> >>>> _______________________
>>> >>>> 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.
>>> >>>>
>>> >>
>>> >>
>>> >> --
>>> >> http://www.needhamsoftware.com (work)
>>> >> http://www.the111shift.com (play)
>>> >>
>>> >>
>>> >> _______________________
>>> >> 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: dev-unsubscribe@solr.apache.org
>>> For additional commands, e-mail: dev-help@solr.apache.org
>>>
>>>
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
> While that does mean that users will be hesitant to move to it for the
time
> being, isn't that kind of the point since we are planning on changing
things?
Exactly, that's the point of major release upgrades. Users will remain
sceptical of moving production to 9x during the early few releases anyway.
Hopefully, we'll fix the APIs during that phase. Towards that, if APIs
change a little, that should be alright, in my opinion. We should just do a
good job of documenting the changes in release notes. We can *start with
all V2 APIs marked experimental in 9.0 and keep unmarking in subsequent
minor releases* as parts of it mature.
> Why do we want users to use something when it's not ready.
For whatever functionality is exposed via V2 APIs, it is ready. There may
be bugs that we'll get to know about only once users start using it. If
there are critical bugs or gaps that we know of, let us address them now
before a 9.0 release.
So, here's my thoughts:
1) Make V2 the default in 9x, because unless it is the default, no one will
use it. If users are so scared, they can stay with 8x or use the older v1
APIs on 9x.
2) If there are critical gaps in V2, lets treat them as blockers before 9.0.
3) Only 1-2 developers have worked on building these APIs, and just 1-2
committers have worked on documenting these APIs. Let us join forces
positively to take this forward and fix all problems (code and
documentation), since they are an amazing quality of life improvement for
everyone using these APIs. These APIs make Solr look much better than
before.
On Wed, Oct 27, 2021 at 8:37 PM Houston Putman <ho...@gmail.com>
wrote:
> Personally I think, while it made a lot of improvements, some aspects of
> the v2 API are clearly downgrades from the v1 API.
> I do think we should move towards deprecating the v1 API, but not until we
> have a solid (and documented of course) v2 or v3 API.
>
> Instead of worrying about v3, I think we should just make v2 the default
>> to drive up adoption and fix it as we go along. APIs will never improve if
>> no one uses it. And no one will use it if we don't document it properly.
>>
>
> If we make v2 the default, that means we can't go and make necessary
> backwards-incompatible changes along the way. We need to make those changes
> first before we go and recommend that people use it.
>
> I agree that the v2 API should be "experimental", or whatever phrase we
> want to use to say that the API might change between minor versions, until
> it's in a much better shape.
>
> While that does mean that users will be hesitant to move to it for the
> time being, isn't that kind of the point since we are planning on changing
> things? Why do we want users to use something when it's not ready.
> I agree that it's harder to improve an API that no one uses, but more
> importantly (to me) no one will use an API that breaks on them after
> upgrading a minor version, unless they are explicitly told this can happen.
>
> I think there should be some indicator to users about the quality and
>> guarantees around the v2 API, but I'm not especially attached to
>> "experimental" if it's disliked.
>>
>
> 100% agreed here. (Wrote my previous paragraphs before your reply)
>
> If there were discussions around huge changes...
>
>
> Completely agreed here as well. My big concerns are purely "cosmetic"
> (HTTP Methods, API paths, HTTP Status Codes, etc). If we want to start
> using protobuf or something like that, then yes a v3 will be required.
>
> - Houston
>
> On Wed, Oct 27, 2021 at 11:01 AM Jason Gerlowski <ge...@gmail.com>
> wrote:
>
>> > unfortunately it's been released without that moniker for a long time
>> ... we may need to go v3 if we want to change things since people will
>> understandably have written code against it.
>>
>> The idea of breaking "existing v2 users" is definitely a sticking
>> point. But I think there's a strong case that these users are a tiny
>> tiny minority out there: see the past lack of v2 docs, SolrJ support,
>> mailing list traffic or bug reports on v2, etc. And if you accept
>> that, then deciding to rigidly follow backcompat or not comes down to
>> deciding what offers the community as a whole more benefit:
>> maintaining API compatibility to avoid code breaks for this tiny
>> minority, or getting a more polished API over the finish line sooner
>> for use by all.
>>
>> Gus - you're right that we could do a "v3"-type approach here while
>> maintaining backcompat, but I agree with Eric's point that v3 would be
>> a step back in terms of forward progress on getting a new API out. If
>> there were discussions around huge changes (switching to protobuf,
>> removing commonly used APIs, etc.) that step back would be worth it.
>> But for the pretty minor backcompat changes that have been proposed
>> (e.g. renaming params for consistency "configSet" -> "config") - it
>> just seems like overkill. If we're worried about upsetting users,
>> there's lots we can do in terms of signaling any potential changes
>> well in advance via ANNOUNCE emails, ref guide docs, etc.
>>
>> > What if we dropped the term “experimental”, because that implies that
>> the v2 API might not be actually adopted
>>
>> I think there should be some indicator to users about the quality and
>> guarantees around the v2 API, but I'm not especially attached to
>> "experimental" if it's disliked. That said, maybe we should reach
>> consensus on some of the other questions (i.e. backcompat
>> implications) and then figure out what word/label best conveys things.
>>
>> Jason
>>
>> On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya
>> <ic...@gmail.com> wrote:
>> >
>> > > While the v2 has been out for a long time, do we actually have
>> evidence that it is widely used and has significant code written against it?
>> >
>> > I don't think anyone uses V2 APIs. No one wants to use undocumented
>> APIs.
>> >
>> > > I worry that deciding to go with v3 it going to prevent any forward
>> progress
>> >
>> > Instead of worrying about v3, I think we should just make v2 the
>> default to drive up adoption and fix it as we go along. APIs will never
>> improve if no one uses it. And no one will use it if we don't document it
>> properly.
>> >
>> > > What if we dropped the term “experimental”, because that implies that
>> the v2 API might not be actually adopted….
>> > +1
>> >
>> > > What if we say “v1 is the Long Term Supported version of the API, and
>> v2 is the evolving to be better and better API, monitor the release notes
>> for the changes ;-)"
>> >
>> > I would rather that we say v1 is old and crappy and we'll drop support
>> for it soon. V2 is evolving to be better API, and you're encouraged to use
>> it.
>> >
>> >
>> >
>> >
>> >
>> > On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <
>> epugh@opensourceconnections.com> wrote:
>> >>
>> >> While the v2 has been out for a long time, do we actually have
>> evidence that it is widely used and has significant code written against it?
>> >>
>> >> When I look at various components/packages that have been written
>> around Solr, I don’t see the v2 API used. For example, Project Blacklight,
>> a UI for Solr is solidly on v1.
>> >>
>> >> I worry that deciding to go with v3 it going to prevent any forward
>> progress…. Having gone through the effort to document v2 in the Ref Guide,
>> I’m not dying to now go and add a v3 for all the examples ;-(. I’d
>> rather just update the v2 in place and celebrate the “9.1 has cleaned up
>> the X API, come check out the new support for Y” ;-)
>> >>
>> >> What if we dropped the term “experimental”, because that implies that
>> the v2 API might not be actually adopted….
>> >>
>> >> What if we say “v1 is the Long Term Supported version of the API, and
>> v2 is the evolving to be better and better API, monitor the release notes
>> for the changes ;-)"
>> >>
>> >>
>> >>
>> >> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
>> >>
>> >> And I think v1/v2 should be split into their own servlets leveraging
>> common code by calling utilities, or composing with other objects rather
>> than inheriting and getting in each other's way. I think v2 could change a
>> lot so experimental seems appropriate, but unfortunately it's been released
>> without that moniker for a long time... we may need to go v3 if we want to
>> change things since people will understandably have written code against it.
>> >>
>> >> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <
>> arafalov@gmail.com> wrote:
>> >>>
>> >>> I felt that V2's lack of support for defaults was a serious
>> architectural issue that is hard to just close eyes on.
>> >>>
>> >>> Regards,
>> >>> Alex
>> >>>
>> >>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
>> epugh@opensourceconnections.com> wrote:
>> >>>>
>> >>>> I’d very much like to see this as well.
>> >>>>
>> >>>> I’ve been thinking that I would look to migrate the Solr Admin to
>> using the v2 API, and I suspect it will identify any number of gaps/areas
>> of improvement in the v2 API itself.
>> >>>>
>> >>>>
>> >>>>
>> >>>>
>> >>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
>> wrote:
>> >>>>
>> >>>> Hi all,
>> >>>>
>> >>>> I'm starting this thread to highlight a subject that came up in the
>> >>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>> >>>> should the v2 API be considered "experimental"?
>> >>>>
>> >>>> We haven't explicitly called the v2 API experimental up to this
>> point,
>> >>>> but I'd argue that in essence it already is. In previous releases it
>> >>>> was largely undocumented, had little or no SolrJ support, missed
>> >>>> parity with v1 in terms of endpoints and parameters, and wasn't
>> >>>> included in test randomization. It's hard to imagine how someone
>> >>>> could have been using the v2 API nontrivially in our past releases.
>> >>>>
>> >>>> Treating v2 as "experimental" just feels much more like calling a
>> >>>> "spade" a "spade", and sends a more accurate signal to our users. It
>> >>>> would also have practical benefits: experimental code is
>> traditionally
>> >>>> free from backcompat guarantees, so an "experimental" designation
>> >>>> would remove a big impediment for those improving the v2 API.
>> >>>>
>> >>>> Knowingly setting backcompat aside is always scary, and of course, we
>> >>>> don't have any means to know for sure how many users v2 has today.
>> >>>> But if we judge from the few signals we do have, the number must be
>> >>>> very small. e.g. The last user-list email that mentions a v2 API
>> path
>> >>>> is "Atomic update error with JSON handler" from May of 2018!
>> >>>>
>> >>>> Potential backcompat breaks might inconvenience that small set of
>> >>>> users, but that inconvenience would be vastly outweighed by the
>> >>>> benefit to all our users of getting a cleaner, more consistent API
>> out
>> >>>> sooner.
>> >>>>
>> >>>> Anyway, that's my pitch. Would love to hear what people think about
>> the idea.
>> >>>>
>> >>>> Best,
>> >>>>
>> >>>> Jason
>> >>>>
>> >>>> ---------------------------------------------------------------------
>> >>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> >>>> For additional commands, e-mail: dev-help@solr.apache.org
>> >>>>
>> >>>>
>> >>>> _______________________
>> >>>> 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.
>> >>>>
>> >>
>> >>
>> >> --
>> >> http://www.needhamsoftware.com (work)
>> >> http://www.the111shift.com (play)
>> >>
>> >>
>> >> _______________________
>> >> 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: dev-unsubscribe@solr.apache.org
>> For additional commands, e-mail: dev-help@solr.apache.org
>>
>>
Re: Should v2 API be "experimental"
Posted by Houston Putman <ho...@gmail.com>.
Personally I think, while it made a lot of improvements, some aspects of
the v2 API are clearly downgrades from the v1 API.
I do think we should move towards deprecating the v1 API, but not until we
have a solid (and documented of course) v2 or v3 API.
Instead of worrying about v3, I think we should just make v2 the default to
> drive up adoption and fix it as we go along. APIs will never improve if no
> one uses it. And no one will use it if we don't document it properly.
>
If we make v2 the default, that means we can't go and make necessary
backwards-incompatible changes along the way. We need to make those changes
first before we go and recommend that people use it.
I agree that the v2 API should be "experimental", or whatever phrase we
want to use to say that the API might change between minor versions, until
it's in a much better shape.
While that does mean that users will be hesitant to move to it for the time
being, isn't that kind of the point since we are planning on changing
things? Why do we want users to use something when it's not ready.
I agree that it's harder to improve an API that no one uses, but more
importantly (to me) no one will use an API that breaks on them after
upgrading a minor version, unless they are explicitly told this can happen.
I think there should be some indicator to users about the quality and
> guarantees around the v2 API, but I'm not especially attached to
> "experimental" if it's disliked.
>
100% agreed here. (Wrote my previous paragraphs before your reply)
If there were discussions around huge changes...
Completely agreed here as well. My big concerns are purely "cosmetic" (HTTP
Methods, API paths, HTTP Status Codes, etc). If we want to start using
protobuf or something like that, then yes a v3 will be required.
- Houston
On Wed, Oct 27, 2021 at 11:01 AM Jason Gerlowski <ge...@gmail.com>
wrote:
> > unfortunately it's been released without that moniker for a long time
> ... we may need to go v3 if we want to change things since people will
> understandably have written code against it.
>
> The idea of breaking "existing v2 users" is definitely a sticking
> point. But I think there's a strong case that these users are a tiny
> tiny minority out there: see the past lack of v2 docs, SolrJ support,
> mailing list traffic or bug reports on v2, etc. And if you accept
> that, then deciding to rigidly follow backcompat or not comes down to
> deciding what offers the community as a whole more benefit:
> maintaining API compatibility to avoid code breaks for this tiny
> minority, or getting a more polished API over the finish line sooner
> for use by all.
>
> Gus - you're right that we could do a "v3"-type approach here while
> maintaining backcompat, but I agree with Eric's point that v3 would be
> a step back in terms of forward progress on getting a new API out. If
> there were discussions around huge changes (switching to protobuf,
> removing commonly used APIs, etc.) that step back would be worth it.
> But for the pretty minor backcompat changes that have been proposed
> (e.g. renaming params for consistency "configSet" -> "config") - it
> just seems like overkill. If we're worried about upsetting users,
> there's lots we can do in terms of signaling any potential changes
> well in advance via ANNOUNCE emails, ref guide docs, etc.
>
> > What if we dropped the term “experimental”, because that implies that
> the v2 API might not be actually adopted
>
> I think there should be some indicator to users about the quality and
> guarantees around the v2 API, but I'm not especially attached to
> "experimental" if it's disliked. That said, maybe we should reach
> consensus on some of the other questions (i.e. backcompat
> implications) and then figure out what word/label best conveys things.
>
> Jason
>
> On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya
> <ic...@gmail.com> wrote:
> >
> > > While the v2 has been out for a long time, do we actually have
> evidence that it is widely used and has significant code written against it?
> >
> > I don't think anyone uses V2 APIs. No one wants to use undocumented APIs.
> >
> > > I worry that deciding to go with v3 it going to prevent any forward
> progress
> >
> > Instead of worrying about v3, I think we should just make v2 the default
> to drive up adoption and fix it as we go along. APIs will never improve if
> no one uses it. And no one will use it if we don't document it properly.
> >
> > > What if we dropped the term “experimental”, because that implies that
> the v2 API might not be actually adopted….
> > +1
> >
> > > What if we say “v1 is the Long Term Supported version of the API, and
> v2 is the evolving to be better and better API, monitor the release notes
> for the changes ;-)"
> >
> > I would rather that we say v1 is old and crappy and we'll drop support
> for it soon. V2 is evolving to be better API, and you're encouraged to use
> it.
> >
> >
> >
> >
> >
> > On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <
> epugh@opensourceconnections.com> wrote:
> >>
> >> While the v2 has been out for a long time, do we actually have evidence
> that it is widely used and has significant code written against it?
> >>
> >> When I look at various components/packages that have been written
> around Solr, I don’t see the v2 API used. For example, Project Blacklight,
> a UI for Solr is solidly on v1.
> >>
> >> I worry that deciding to go with v3 it going to prevent any forward
> progress…. Having gone through the effort to document v2 in the Ref Guide,
> I’m not dying to now go and add a v3 for all the examples ;-(. I’d
> rather just update the v2 in place and celebrate the “9.1 has cleaned up
> the X API, come check out the new support for Y” ;-)
> >>
> >> What if we dropped the term “experimental”, because that implies that
> the v2 API might not be actually adopted….
> >>
> >> What if we say “v1 is the Long Term Supported version of the API, and
> v2 is the evolving to be better and better API, monitor the release notes
> for the changes ;-)"
> >>
> >>
> >>
> >> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
> >>
> >> And I think v1/v2 should be split into their own servlets leveraging
> common code by calling utilities, or composing with other objects rather
> than inheriting and getting in each other's way. I think v2 could change a
> lot so experimental seems appropriate, but unfortunately it's been released
> without that moniker for a long time... we may need to go v3 if we want to
> change things since people will understandably have written code against it.
> >>
> >> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <
> arafalov@gmail.com> wrote:
> >>>
> >>> I felt that V2's lack of support for defaults was a serious
> architectural issue that is hard to just close eyes on.
> >>>
> >>> Regards,
> >>> Alex
> >>>
> >>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
> epugh@opensourceconnections.com> wrote:
> >>>>
> >>>> I’d very much like to see this as well.
> >>>>
> >>>> I’ve been thinking that I would look to migrate the Solr Admin to
> using the v2 API, and I suspect it will identify any number of gaps/areas
> of improvement in the v2 API itself.
> >>>>
> >>>>
> >>>>
> >>>>
> >>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
> wrote:
> >>>>
> >>>> Hi all,
> >>>>
> >>>> I'm starting this thread to highlight a subject that came up in the
> >>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
> >>>> should the v2 API be considered "experimental"?
> >>>>
> >>>> We haven't explicitly called the v2 API experimental up to this point,
> >>>> but I'd argue that in essence it already is. In previous releases it
> >>>> was largely undocumented, had little or no SolrJ support, missed
> >>>> parity with v1 in terms of endpoints and parameters, and wasn't
> >>>> included in test randomization. It's hard to imagine how someone
> >>>> could have been using the v2 API nontrivially in our past releases.
> >>>>
> >>>> Treating v2 as "experimental" just feels much more like calling a
> >>>> "spade" a "spade", and sends a more accurate signal to our users. It
> >>>> would also have practical benefits: experimental code is traditionally
> >>>> free from backcompat guarantees, so an "experimental" designation
> >>>> would remove a big impediment for those improving the v2 API.
> >>>>
> >>>> Knowingly setting backcompat aside is always scary, and of course, we
> >>>> don't have any means to know for sure how many users v2 has today.
> >>>> But if we judge from the few signals we do have, the number must be
> >>>> very small. e.g. The last user-list email that mentions a v2 API path
> >>>> is "Atomic update error with JSON handler" from May of 2018!
> >>>>
> >>>> Potential backcompat breaks might inconvenience that small set of
> >>>> users, but that inconvenience would be vastly outweighed by the
> >>>> benefit to all our users of getting a cleaner, more consistent API out
> >>>> sooner.
> >>>>
> >>>> Anyway, that's my pitch. Would love to hear what people think about
> the idea.
> >>>>
> >>>> Best,
> >>>>
> >>>> Jason
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> >>>> For additional commands, e-mail: dev-help@solr.apache.org
> >>>>
> >>>>
> >>>> _______________________
> >>>> 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.
> >>>>
> >>
> >>
> >> --
> >> http://www.needhamsoftware.com (work)
> >> http://www.the111shift.com (play)
> >>
> >>
> >> _______________________
> >> 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: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
Re: Should v2 API be "experimental"
Posted by Jason Gerlowski <ge...@gmail.com>.
> unfortunately it's been released without that moniker for a long time ... we may need to go v3 if we want to change things since people will understandably have written code against it.
The idea of breaking "existing v2 users" is definitely a sticking
point. But I think there's a strong case that these users are a tiny
tiny minority out there: see the past lack of v2 docs, SolrJ support,
mailing list traffic or bug reports on v2, etc. And if you accept
that, then deciding to rigidly follow backcompat or not comes down to
deciding what offers the community as a whole more benefit:
maintaining API compatibility to avoid code breaks for this tiny
minority, or getting a more polished API over the finish line sooner
for use by all.
Gus - you're right that we could do a "v3"-type approach here while
maintaining backcompat, but I agree with Eric's point that v3 would be
a step back in terms of forward progress on getting a new API out. If
there were discussions around huge changes (switching to protobuf,
removing commonly used APIs, etc.) that step back would be worth it.
But for the pretty minor backcompat changes that have been proposed
(e.g. renaming params for consistency "configSet" -> "config") - it
just seems like overkill. If we're worried about upsetting users,
there's lots we can do in terms of signaling any potential changes
well in advance via ANNOUNCE emails, ref guide docs, etc.
> What if we dropped the term “experimental”, because that implies that the v2 API might not be actually adopted
I think there should be some indicator to users about the quality and
guarantees around the v2 API, but I'm not especially attached to
"experimental" if it's disliked. That said, maybe we should reach
consensus on some of the other questions (i.e. backcompat
implications) and then figure out what word/label best conveys things.
Jason
On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya
<ic...@gmail.com> wrote:
>
> > While the v2 has been out for a long time, do we actually have evidence that it is widely used and has significant code written against it?
>
> I don't think anyone uses V2 APIs. No one wants to use undocumented APIs.
>
> > I worry that deciding to go with v3 it going to prevent any forward progress
>
> Instead of worrying about v3, I think we should just make v2 the default to drive up adoption and fix it as we go along. APIs will never improve if no one uses it. And no one will use it if we don't document it properly.
>
> > What if we dropped the term “experimental”, because that implies that the v2 API might not be actually adopted….
> +1
>
> > What if we say “v1 is the Long Term Supported version of the API, and v2 is the evolving to be better and better API, monitor the release notes for the changes ;-)"
>
> I would rather that we say v1 is old and crappy and we'll drop support for it soon. V2 is evolving to be better API, and you're encouraged to use it.
>
>
>
>
>
> On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <ep...@opensourceconnections.com> wrote:
>>
>> While the v2 has been out for a long time, do we actually have evidence that it is widely used and has significant code written against it?
>>
>> When I look at various components/packages that have been written around Solr, I don’t see the v2 API used. For example, Project Blacklight, a UI for Solr is solidly on v1.
>>
>> I worry that deciding to go with v3 it going to prevent any forward progress…. Having gone through the effort to document v2 in the Ref Guide, I’m not dying to now go and add a v3 for all the examples ;-(. I’d rather just update the v2 in place and celebrate the “9.1 has cleaned up the X API, come check out the new support for Y” ;-)
>>
>> What if we dropped the term “experimental”, because that implies that the v2 API might not be actually adopted….
>>
>> What if we say “v1 is the Long Term Supported version of the API, and v2 is the evolving to be better and better API, monitor the release notes for the changes ;-)"
>>
>>
>>
>> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
>>
>> And I think v1/v2 should be split into their own servlets leveraging common code by calling utilities, or composing with other objects rather than inheriting and getting in each other's way. I think v2 could change a lot so experimental seems appropriate, but unfortunately it's been released without that moniker for a long time... we may need to go v3 if we want to change things since people will understandably have written code against it.
>>
>> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <ar...@gmail.com> wrote:
>>>
>>> I felt that V2's lack of support for defaults was a serious architectural issue that is hard to just close eyes on.
>>>
>>> Regards,
>>> Alex
>>>
>>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <ep...@opensourceconnections.com> wrote:
>>>>
>>>> I’d very much like to see this as well.
>>>>
>>>> I’ve been thinking that I would look to migrate the Solr Admin to using the v2 API, and I suspect it will identify any number of gaps/areas of improvement in the v2 API itself.
>>>>
>>>>
>>>>
>>>>
>>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com> wrote:
>>>>
>>>> Hi all,
>>>>
>>>> I'm starting this thread to highlight a subject that came up in the
>>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>>>> should the v2 API be considered "experimental"?
>>>>
>>>> We haven't explicitly called the v2 API experimental up to this point,
>>>> but I'd argue that in essence it already is. In previous releases it
>>>> was largely undocumented, had little or no SolrJ support, missed
>>>> parity with v1 in terms of endpoints and parameters, and wasn't
>>>> included in test randomization. It's hard to imagine how someone
>>>> could have been using the v2 API nontrivially in our past releases.
>>>>
>>>> Treating v2 as "experimental" just feels much more like calling a
>>>> "spade" a "spade", and sends a more accurate signal to our users. It
>>>> would also have practical benefits: experimental code is traditionally
>>>> free from backcompat guarantees, so an "experimental" designation
>>>> would remove a big impediment for those improving the v2 API.
>>>>
>>>> Knowingly setting backcompat aside is always scary, and of course, we
>>>> don't have any means to know for sure how many users v2 has today.
>>>> But if we judge from the few signals we do have, the number must be
>>>> very small. e.g. The last user-list email that mentions a v2 API path
>>>> is "Atomic update error with JSON handler" from May of 2018!
>>>>
>>>> Potential backcompat breaks might inconvenience that small set of
>>>> users, but that inconvenience would be vastly outweighed by the
>>>> benefit to all our users of getting a cleaner, more consistent API out
>>>> sooner.
>>>>
>>>> Anyway, that's my pitch. Would love to hear what people think about the idea.
>>>>
>>>> Best,
>>>>
>>>> Jason
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>>>> For additional commands, e-mail: dev-help@solr.apache.org
>>>>
>>>>
>>>> _______________________
>>>> 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.
>>>>
>>
>>
>> --
>> http://www.needhamsoftware.com (work)
>> http://www.the111shift.com (play)
>>
>>
>> _______________________
>> 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: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Should v2 API be "experimental"
Posted by Ishan Chattopadhyaya <ic...@gmail.com>.
> While the v2 has been out for a long time, do we actually have evidence
that it is widely used and has significant code written against it?
I don't think anyone uses V2 APIs. No one wants to use undocumented APIs.
> I worry that deciding to go with v3 it going to prevent any forward
progress
Instead of worrying about v3, I think we should just make v2 the default to
drive up adoption and fix it as we go along. APIs will never improve if no
one uses it. And no one will use it if we don't document it properly.
> What if we dropped the term “experimental”, because that implies that the
v2 API might not be actually adopted….
+1
> What if we say “v1 is the Long Term Supported version of the API, and v2
is the evolving to be better and better API, monitor the release notes for
the changes ;-)"
I would rather that we say v1 is old and crappy and we'll drop support for
it soon. V2 is evolving to be better API, and you're encouraged to use it.
On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <ep...@opensourceconnections.com>
wrote:
> While the v2 has been out for a long time, do we actually have evidence
> that it is widely used and has significant code written against it?
>
> When I look at various components/packages that have been written around
> Solr, I don’t see the v2 API used. For example, Project Blacklight, a UI
> for Solr is solidly on v1.
>
> I worry that deciding to go with v3 it going to prevent any forward
> progress…. Having gone through the effort to document v2 in the Ref Guide,
> I’m not dying to now go and add a v3 for all the examples ;-(. I’d
> rather just update the v2 in place and celebrate the “9.1 has cleaned up
> the X API, come check out the new support for Y” ;-)
>
> What if we dropped the term “experimental”, because that implies that the
> v2 API might not be actually adopted….
>
> What if we say “v1 is the Long Term Supported version of the API, and v2
> is the evolving to be better and better API, monitor the release notes for
> the changes ;-)"
>
>
>
> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
>
> And I think v1/v2 should be split into their own servlets leveraging
> common code by calling utilities, or composing with other objects rather
> than inheriting and getting in each other's way. I think v2 could change a
> lot so experimental seems appropriate, but unfortunately it's been released
> without that moniker for a long time... we may need to go v3 if we want to
> change things since people will understandably have written code against it.
>
> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <ar...@gmail.com>
> wrote:
>
>> I felt that V2's lack of support for defaults was a serious architectural
>> issue that is hard to just close eyes on.
>>
>> Regards,
>> Alex
>>
>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
>> epugh@opensourceconnections.com> wrote:
>>
>>> I’d very much like to see this as well.
>>>
>>> I’ve been thinking that I would look to migrate the Solr Admin to using
>>> the v2 API, and I suspect it will identify any number of gaps/areas of
>>> improvement in the v2 API itself.
>>>
>>>
>>>
>>>
>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
>>> wrote:
>>>
>>> Hi all,
>>>
>>> I'm starting this thread to highlight a subject that came up in the
>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>>> should the v2 API be considered "experimental"?
>>>
>>> We haven't explicitly called the v2 API experimental up to this point,
>>> but I'd argue that in essence it already is. In previous releases it
>>> was largely undocumented, had little or no SolrJ support, missed
>>> parity with v1 in terms of endpoints and parameters, and wasn't
>>> included in test randomization. It's hard to imagine how someone
>>> could have been using the v2 API nontrivially in our past releases.
>>>
>>> Treating v2 as "experimental" just feels much more like calling a
>>> "spade" a "spade", and sends a more accurate signal to our users. It
>>> would also have practical benefits: experimental code is traditionally
>>> free from backcompat guarantees, so an "experimental" designation
>>> would remove a big impediment for those improving the v2 API.
>>>
>>> Knowingly setting backcompat aside is always scary, and of course, we
>>> don't have any means to know for sure how many users v2 has today.
>>> But if we judge from the few signals we do have, the number must be
>>> very small. e.g. The last user-list email that mentions a v2 API path
>>> is "Atomic update error with JSON handler" from May of 2018!
>>>
>>> Potential backcompat breaks might inconvenience that small set of
>>> users, but that inconvenience would be vastly outweighed by the
>>> benefit to all our users of getting a cleaner, more consistent API out
>>> sooner.
>>>
>>> Anyway, that's my pitch. Would love to hear what people think about the
>>> idea.
>>>
>>> Best,
>>>
>>> Jason
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>>> <de...@solr.apache.org>
>>> For additional commands, e-mail: dev-help@solr.apache.org
>>> <de...@solr.apache.org>
>>>
>>>
>>> _______________________
>>> *Eric Pugh **| *Founder & CEO | OpenSource Connections, LLC | 434.466.1467
>>> | http://www.opensourceconnections.com | My Free/Busy
>>> <http://tinyurl.com/eric-cal>
>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
>>> <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
>>> 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.
>>>
>>>
>
> --
> http://www.needhamsoftware.com (work)
> http://www.the111shift.com (play)
>
>
> _______________________
> *Eric Pugh **| *Founder & CEO | OpenSource Connections, LLC | 434.466.1467
> | http://www.opensourceconnections.com | My Free/Busy
> <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
> <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
>
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
While the v2 has been out for a long time, do we actually have evidence that it is widely used and has significant code written against it?
When I look at various components/packages that have been written around Solr, I don’t see the v2 API used. For example, Project Blacklight, a UI for Solr is solidly on v1.
I worry that deciding to go with v3 it going to prevent any forward progress…. Having gone through the effort to document v2 in the Ref Guide, I’m not dying to now go and add a v3 for all the examples ;-(. I’d rather just update the v2 in place and celebrate the “9.1 has cleaned up the X API, come check out the new support for Y” ;-)
What if we dropped the term “experimental”, because that implies that the v2 API might not be actually adopted….
What if we say “v1 is the Long Term Supported version of the API, and v2 is the evolving to be better and better API, monitor the release notes for the changes ;-)"
> On Oct 27, 2021, at 9:07 AM, Gus Heck <gu...@gmail.com> wrote:
>
> And I think v1/v2 should be split into their own servlets leveraging common code by calling utilities, or composing with other objects rather than inheriting and getting in each other's way. I think v2 could change a lot so experimental seems appropriate, but unfortunately it's been released without that moniker for a long time... we may need to go v3 if we want to change things since people will understandably have written code against it.
>
> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <arafalov@gmail.com <ma...@gmail.com>> wrote:
> I felt that V2's lack of support for defaults was a serious architectural issue that is hard to just close eyes on.
>
> Regards,
> Alex
>
> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <epugh@opensourceconnections.com <ma...@opensourceconnections.com>> wrote:
> I’d very much like to see this as well.
>
> I’ve been thinking that I would look to migrate the Solr Admin to using the v2 API, and I suspect it will identify any number of gaps/areas of improvement in the v2 API itself.
>
>
>
>
>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <gerlowskija@gmail.com <ma...@gmail.com>> wrote:
>>
>> Hi all,
>>
>> I'm starting this thread to highlight a subject that came up in the
>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>> should the v2 API be considered "experimental"?
>>
>> We haven't explicitly called the v2 API experimental up to this point,
>> but I'd argue that in essence it already is. In previous releases it
>> was largely undocumented, had little or no SolrJ support, missed
>> parity with v1 in terms of endpoints and parameters, and wasn't
>> included in test randomization. It's hard to imagine how someone
>> could have been using the v2 API nontrivially in our past releases.
>>
>> Treating v2 as "experimental" just feels much more like calling a
>> "spade" a "spade", and sends a more accurate signal to our users. It
>> would also have practical benefits: experimental code is traditionally
>> free from backcompat guarantees, so an "experimental" designation
>> would remove a big impediment for those improving the v2 API.
>>
>> Knowingly setting backcompat aside is always scary, and of course, we
>> don't have any means to know for sure how many users v2 has today.
>> But if we judge from the few signals we do have, the number must be
>> very small. e.g. The last user-list email that mentions a v2 API path
>> is "Atomic update error with JSON handler" from May of 2018!
>>
>> Potential backcompat breaks might inconvenience that small set of
>> users, but that inconvenience would be vastly outweighed by the
>> benefit to all our users of getting a cleaner, more consistent API out
>> sooner.
>>
>> Anyway, that's my pitch. Would love to hear what people think about the idea.
>>
>> Best,
>>
>> Jason
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org <ma...@solr.apache.org>
>> For additional commands, e-mail: dev-help@solr.apache.org <ma...@solr.apache.org>
>>
>
> _______________________
> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
>
>
> --
> http://www.needhamsoftware.com <http://www.needhamsoftware.com/> (work)
> http://www.the111shift.com <http://www.the111shift.com/> (play)
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.
Re: Should v2 API be "experimental"
Posted by Gus Heck <gu...@gmail.com>.
And I think v1/v2 should be split into their own servlets leveraging common
code by calling utilities, or composing with other objects rather than
inheriting and getting in each other's way. I think v2 could change a lot
so experimental seems appropriate, but unfortunately it's been released
without that moniker for a long time... we may need to go v3 if we want to
change things since people will understandably have written code against it.
On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <ar...@gmail.com>
wrote:
> I felt that V2's lack of support for defaults was a serious architectural
> issue that is hard to just close eyes on.
>
> Regards,
> Alex
>
> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
> epugh@opensourceconnections.com> wrote:
>
>> I’d very much like to see this as well.
>>
>> I’ve been thinking that I would look to migrate the Solr Admin to using
>> the v2 API, and I suspect it will identify any number of gaps/areas of
>> improvement in the v2 API itself.
>>
>>
>>
>>
>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
>> wrote:
>>
>> Hi all,
>>
>> I'm starting this thread to highlight a subject that came up in the
>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
>> should the v2 API be considered "experimental"?
>>
>> We haven't explicitly called the v2 API experimental up to this point,
>> but I'd argue that in essence it already is. In previous releases it
>> was largely undocumented, had little or no SolrJ support, missed
>> parity with v1 in terms of endpoints and parameters, and wasn't
>> included in test randomization. It's hard to imagine how someone
>> could have been using the v2 API nontrivially in our past releases.
>>
>> Treating v2 as "experimental" just feels much more like calling a
>> "spade" a "spade", and sends a more accurate signal to our users. It
>> would also have practical benefits: experimental code is traditionally
>> free from backcompat guarantees, so an "experimental" designation
>> would remove a big impediment for those improving the v2 API.
>>
>> Knowingly setting backcompat aside is always scary, and of course, we
>> don't have any means to know for sure how many users v2 has today.
>> But if we judge from the few signals we do have, the number must be
>> very small. e.g. The last user-list email that mentions a v2 API path
>> is "Atomic update error with JSON handler" from May of 2018!
>>
>> Potential backcompat breaks might inconvenience that small set of
>> users, but that inconvenience would be vastly outweighed by the
>> benefit to all our users of getting a cleaner, more consistent API out
>> sooner.
>>
>> Anyway, that's my pitch. Would love to hear what people think about the
>> idea.
>>
>> Best,
>>
>> Jason
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
>> <de...@solr.apache.org>
>> For additional commands, e-mail: dev-help@solr.apache.org
>> <de...@solr.apache.org>
>>
>>
>> _______________________
>> *Eric Pugh **| *Founder & CEO | OpenSource Connections, LLC | 434.466.1467
>> | http://www.opensourceconnections.com | My Free/Busy
>> <http://tinyurl.com/eric-cal>
>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
>> <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
>> 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.
>>
>>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Should v2 API be "experimental"
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
I felt that V2's lack of support for defaults was a serious architectural
issue that is hard to just close eyes on.
Regards,
Alex
On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, <
epugh@opensourceconnections.com> wrote:
> I’d very much like to see this as well.
>
> I’ve been thinking that I would look to migrate the Solr Admin to using
> the v2 API, and I suspect it will identify any number of gaps/areas of
> improvement in the v2 API itself.
>
>
>
>
> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com>
> wrote:
>
> Hi all,
>
> I'm starting this thread to highlight a subject that came up in the
> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
> should the v2 API be considered "experimental"?
>
> We haven't explicitly called the v2 API experimental up to this point,
> but I'd argue that in essence it already is. In previous releases it
> was largely undocumented, had little or no SolrJ support, missed
> parity with v1 in terms of endpoints and parameters, and wasn't
> included in test randomization. It's hard to imagine how someone
> could have been using the v2 API nontrivially in our past releases.
>
> Treating v2 as "experimental" just feels much more like calling a
> "spade" a "spade", and sends a more accurate signal to our users. It
> would also have practical benefits: experimental code is traditionally
> free from backcompat guarantees, so an "experimental" designation
> would remove a big impediment for those improving the v2 API.
>
> Knowingly setting backcompat aside is always scary, and of course, we
> don't have any means to know for sure how many users v2 has today.
> But if we judge from the few signals we do have, the number must be
> very small. e.g. The last user-list email that mentions a v2 API path
> is "Atomic update error with JSON handler" from May of 2018!
>
> Potential backcompat breaks might inconvenience that small set of
> users, but that inconvenience would be vastly outweighed by the
> benefit to all our users of getting a cleaner, more consistent API out
> sooner.
>
> Anyway, that's my pitch. Would love to hear what people think about the
> idea.
>
> Best,
>
> Jason
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> <de...@solr.apache.org>
> For additional commands, e-mail: dev-help@solr.apache.org
> <de...@solr.apache.org>
>
>
> _______________________
> *Eric Pugh **| *Founder & CEO | OpenSource Connections, LLC | 434.466.1467
> | http://www.opensourceconnections.com | My Free/Busy
> <http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
> <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> 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.
>
>
Re: Should v2 API be "experimental"
Posted by Eric Pugh <ep...@opensourceconnections.com>.
I’d very much like to see this as well.
I’ve been thinking that I would look to migrate the Solr Admin to using the v2 API, and I suspect it will identify any number of gaps/areas of improvement in the v2 API itself.
> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <ge...@gmail.com> wrote:
>
> Hi all,
>
> I'm starting this thread to highlight a subject that came up in the
> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR,
> should the v2 API be considered "experimental"?
>
> We haven't explicitly called the v2 API experimental up to this point,
> but I'd argue that in essence it already is. In previous releases it
> was largely undocumented, had little or no SolrJ support, missed
> parity with v1 in terms of endpoints and parameters, and wasn't
> included in test randomization. It's hard to imagine how someone
> could have been using the v2 API nontrivially in our past releases.
>
> Treating v2 as "experimental" just feels much more like calling a
> "spade" a "spade", and sends a more accurate signal to our users. It
> would also have practical benefits: experimental code is traditionally
> free from backcompat guarantees, so an "experimental" designation
> would remove a big impediment for those improving the v2 API.
>
> Knowingly setting backcompat aside is always scary, and of course, we
> don't have any means to know for sure how many users v2 has today.
> But if we judge from the few signals we do have, the number must be
> very small. e.g. The last user-list email that mentions a v2 API path
> is "Atomic update error with JSON handler" from May of 2018!
>
> Potential backcompat breaks might inconvenience that small set of
> users, but that inconvenience would be vastly outweighed by the
> benefit to all our users of getting a cleaner, more consistent API out
> sooner.
>
> Anyway, that's my pitch. Would love to hear what people think about the idea.
>
> Best,
>
> Jason
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
_______________________
Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
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.