[jira] [Commented] (SOLR-15781) Cosmetic and consistency improvements to v2 API

["Jason Gerlowski (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-15781?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17563238#comment-17563238 ] 

Jason Gerlowski commented on SOLR-15781:
----------------------------------------

Following some preliminary discussion on the [mailing list|https://lists.apache.org/thread/jbdzvlsxrw46mr6qz3xy2tkjc8d93okb], I've put together a [spreadsheet |https://docs.google.com/spreadsheets/d/1HAoBBFPpSiT8mJmgNZKkZAPwfCfPvlc08m5jz3fQBpA/edit?usp=sharing]of specific changes we could make to our v2 APIs to push them in a more REST-ful direction.

The spreadsheet uses a bit of color coding to make things a bit more readable. Most important are the green sections, which highlight a proposed deviation from the current v2 API. Of secondary interest are a few lines of light blue, which I've used to indicate APIs missing from both v1 and v2, but that would be useful eventually to round out and add some uniformity to each REST "resource". I'm not proposing these now - I just thought they were helpful to show the additional uniformity the API could have down the road if we decide to shore up some of those gaps.

*Why REST?*

REST in particular has come up a good bit in previous discussions as being more in keeping with best practices today, and being easier for users to pick up: both big wins for Solr. REST-ful APIs are also much easier to create OpenAPI documentation for, which opens some interesting doors for us like allowing us to have a Swagger UI exposing most/all endpoints, or even auto-generating request/response libraries for Java and other languages.

The devil is absolutely in the details with this sort of thing, so I'm eager for feedback on the specific proposals in the spreadsheet. But I think it makes sense to call out a few trends from the spreadsheet for particular attention here:
 * As might be expected in a move towards REST-fulness, the hypothetical v2 API in the spreadsheet relies on a wider range of path segments than the current v2 API uses.
 * The spreadsheet suggests very few changes to "document-level" APIs, like /select, /tag, /export, /stream, etc. In part because they're harder to fit into the REST model, and in part because users can configure them to be exposed at whatever paths they want.
 ** I can imagine a more REST-ful approach that fits some of these endpoints (e.g. {{POST .../collName/documents}} to index documents, {{GET .../collName/documents/docId}} to real-time-get, etc.), but it doesn't fit everything and, again, this is complicated somewhat since users can define many of these request handlers at their discretion.
 * Some commands (particularly some of the former "collection-admin", "core-admin", and "replication" APIs) are hard to fit into a resource-first model. To handle this, the spreadsheet changes the APIs to be grouped under whatever resource they're most relevant to, on a special {{/commands}} subpath. So core reload and unload would live at {{{}POST /api/cores/coreName/commands{}}}, collection reload would live at {{{}POST /api/collections/collName/commands{}}}, etc.

Anyways, excited to hear what everyone thinks!

> Cosmetic and consistency improvements to v2 API
> -----------------------------------------------
>
>                 Key: SOLR-15781
>                 URL: https://issues.apache.org/jira/browse/SOLR-15781
>             Project: Solr
>          Issue Type: Improvement
>          Components: v2 API
>            Reporter: Jason Gerlowski
>            Priority: Major
>              Labels: V2
>
> While the v2 API is in many ways an improvement over v1 in terms of readability and API best practices, it still has a lot of room for improvement.  The recent "exper
> imental" designation for v2 opens the door to pursuing many of these improvements. 
> This ticket is intended as an umbrella to track resolution of some of the known warts in the current v2 API and some of the improvements that can be made in terms of being more RESTful, etc.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org