[
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: [email protected]
For additional commands, e-mail: [email protected]
