Hey all, Thanks for the quick responses! Overall it sounds like no one objects to the idea of broader changes necessarily, but that there are some concerns about the timing/mechanics (backcompat, target release, etc.) and specific API design (use of HTTP verbs, "URL-bar" friendliness, etc). Hopefully that's a fair summary? A few thoughts on each topic below:
> V2 has been around for several major releases and documented [...] long > enough that we must assume a certain user base already [...] Thus I'm not > sure we should act as if the entire v2 design is up for change I totally understand your concern about burning our users Jan, but I think Eric's response is spot-on: the ability to evolve v2 without backcompat constraints was an explicit rationale in the "Should v2 API be Experimental" thread where we agreed to the designation. What's the purpose of the 'experimental' label, if not to free us up to make changes outside of major-versions (and warn users of that possibility)? As I said then: "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 [...] 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." If the root of your concern is that there might be a chunk of longtime v2 users who haven't seen the shift to 'experimental': is there a documentation/communication change that would assuage your concerns there? A thread on 'announce@' highlighting the change maybe? Or a survey in 'users@' to identify whether there is a v2 user-base out there as you suspect? Something else? I'd love to find a way to address your concerns and still evolve v2 without backcompat, if we can. > It's REALLY nice to be able to try things out with a browser ... [users] may > have absolutely no idea how to use something like curl Hey Shawn, Gus: I agree that "just sharing a URL" is dead simple and can help for less-sophisticated users, or in more locked-down (i.e. dev tool-less) environments. But I agree with Noble's point: using the full range of HTTP methods is about as uniquitous "standard practice" as it gets. We might help less-technically-saavy users by writing a GET-only API, but that would end up being less intuitive for the majority of users who are familiar with and expect that standard practice. That said: if we pursue OpenAPI (which, spoilers: I'd like to) then we would get a nice (e.g.) Swagger UI for free, which should make it easy for any user to send any request with "just a browser". Would that address your concerns? [2] Again, thanks for all the feedback! Best, Jason [1] https://lists.apache.org/thread/t342hl7lvt5b4qmb5vrrh7tvmdjlbb22 [2] https://swagger.io/tools/swagger-ui/ On Thu, Jun 16, 2022 at 9:09 PM Noble Paul <noble.p...@gmail.com> wrote: > > @Shawn > > So, if we move towards an HTTP POST , PUT or DELETE based commands we will > never be able to send a link to others over text format because they work > only on HTTP GET. I think this is an artificial limitation that we are going > to impose on anyone designing an API standard and against the widely adopted > standards in the industry. > > So, if we decide to use all the possible verbs of HTTP, users will have to > either use curL or the admin UI for most commands . However some of the GET > based V2 APIs (there are a lot of them) will continue to work . Please keep > in mind that the GET based APIs are READ apis and the POST/PUT/DELETE APIs > result in modifying the state of the cluster/node. I believe it is a security > vulnerability if we let GET operations perform write operations and we > should get rid of them ASAP > > > > On Fri, Jun 17, 2022 at 5:12 AM Shawn Heisey <apa...@elyograg.org> wrote: >> >> On 6/16/22 09:07, Gus Heck wrote: >> >> > I'm all for standardizing on v2 (or something like it) but one key >> > concern I have is that when the only access I have to a client's >> > server is via a web browser, possibly from a machine they control and >> > on which I can't install tools, I'd like the only barrier to my >> > running necessary admin commands is their (hopefully) configured >> > security controls (RBAC/JWT/whatever). It's a loss of functionality if >> > a REST client program, plugin or curl is *required*. Those tools are >> > good things, but the ability to fully control solr directly from a >> > browser (if properly authenticated) is a good feature we shouldn't lose. >> >> I agree with this. >> >> It's REALLY nice to be able to try things out with a browser, or to >> issue infrequently-used admin requests with a browser. Or to send >> somebody a URL with a note that says "This is what I am thinking." The >> v1 API makes this possible, and I have abused it in this way a LOT. I >> know someone is going to say "sending a body is trivial with curl." But >> the person I am sending the message to may have absolutely no idea how >> to use something like curl, and they may be on a stock windows setup >> that doesn't have any of those cool tools available. >> >> I'm OK with such fiddling happening via the admin UI ... but I don't >> think the admin UI is as feature-complete as it needs to be for an API >> that *requires* a body in the request to work. And it's very important >> from my perspective that I can send a URL to someone that demonstrates >> how to do something that will ultimately happen with a client that knows >> how to send request bodies. >> >> Thanks, >> Shawn >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@solr.apache.org >> For additional commands, e-mail: dev-h...@solr.apache.org >> > > > -- > ----------------------------------------------------- > Noble Paul --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@solr.apache.org For additional commands, e-mail: dev-h...@solr.apache.org
