[
https://issues.apache.org/jira/browse/SOLR-15737?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17565076#comment-17565076
]
Jason Gerlowski commented on SOLR-15737:
----------------------------------------
It occurred to me recently that this ticket (and its children) would make great
starting points for new developers. With that in mind I figured I'd give a bit
more information and step-by-step to make this more tempting to pick up.
h2. *APIs in Solr*
Solr's original v1 APIs are defined in classes called "RequestHandler"s (based
on the Jetty interface with the same name). These expose metadata for each API
in various methods. The actual API logic typically lives in the
{{handleRequestBody}} method.
v2 APIs on the other hand are defined in classes called, fittingly, "Api"s. Few
v2 endpoints actually implement the Api interface however. Instead v2 endpoints
can be defined in any class that include a particular series of annotations
(similar to those seen in JAX-RS libraries like Jersey). By convention, these
classes are named to end with the suffix "API", e.g.
[AddReplicaAPI|https://github.com/apache/solr/blob/c99af207c761ec34812ef1cc3054eb2804b7448b/solr/core/src/java/org/apache/solr/handler/admin/api/AddReplicaAPI.java]
Since in most cases v2 APIs expose the same functionality that already exists
in a RequestHandler somewhere, most V2 classes are just a thin "shim" that
takes in a request matching the improved v2 format, modifies it to match the
inputs that v1 expects, and then calls the v1 RequestHandler holding the
underlying functionality.
v2 APIs today are also "registered" by association with a particular
RequestHandler. This is useful to ensure that the v1 and v2 APIs for particular
functionality are always present (or not) in conjunction with one another. The
{{registerV2}} boolean RequestHandler method indicates whether a RequestHandler
has v2 APIs to register, and the {{getApis}} method allows those Apis to be
fetched.
h2. *Creating a New V2 API*
Creating a V2 API is often just a matter of following a few simple steps:
1. *Create the class to hold your v2 API* By convention, API class names
generally end with "API".
2. *Define Payload class if necessary* Many v2 POST APIs share a similar syntax
for executing "commands". These have request bodies that look like:
{code:java}
{ "commandName": {...commandobject...}}
{code}
APIs whose request bodies match this format can define a "Payload" class, whose
contents represent the "commandobject" section of the JSON above. Solr can
then detect and serialize request bodies into the Payload class, allowing the
v2 API to use a nice strongly typed object in the method implementing the API
(see below). For an example payload class and its usage, see AddReplicaAPI's
[definition|https://github.com/apache/solr/blob/c99af207c761ec34812ef1cc3054eb2804b7448b/solr/core/src/java/org/apache/solr/handler/admin/api/AddReplicaAPI.java]
and
[payload|https://github.com/apache/solr/blob/f08f7bb3ef90381078e427f0d164a9f13afe070c/solr/solrj/src/java/org/apache/solr/client/solrj/request/beans/AddReplicaPayload.java]
classes.
By convention, payload class names typically end with "Payload".
3. *Add a method to house the v2 API logic* Methods should be in one of two
forms, depending on whether the special "command" syntax is being used.
{code:java}
// Normal case
public void methodName(SolrQueryRequest req, SolrQueryResponse rsp) {...}
// v2 command/payload syntax (only available for POST/PUT APIs)
public void methodName(PayloadObj<SomeApiPayload> obj) {...}
{code}
4. *Add annotations to define the API's HTTP method, path, etc.* See the
annotations on
[AddReplicaAPI|https://github.com/apache/solr/blob/c99af207c761ec34812ef1cc3054eb2804b7448b/solr/core/src/java/org/apache/solr/handler/admin/api/AddReplicaAPI.java]
and
[DeleteReplicaAPI|https://github.com/apache/solr/blob/c99af207c761ec34812ef1cc3054eb2804b7448b/solr/core/src/java/org/apache/solr/handler/admin/api/DeleteReplicaAPI.java]
for examples of the command-based and regular syntax, respectively.
5. *Add v2 -> v1 syntax conversion to API method* If necessary. Some v2 APIs
differ from their v1 counterparts by path alone. In this case the relevant
RequestHandler can be invoked without conversion.
6. *Modify the relevant RequestHandler to register the new v2 API* Examples can
be found in any
[RequestHandler.getApi|https://github.com/apache/solr/blob/ab6d77a13d9e5ce6c699f26e9d9e9d8d6b81c17e/solr/core/src/java/org/apache/solr/handler/SchemaHandler.java#L315]
method
And that's it! Hope this helps the community divide-and-conquer the work a
bit, or enables newdevs to get their feet wet working on Solr.
> Ensure all (desired) v1 APIs have v2 equivalent
> -----------------------------------------------
>
> Key: SOLR-15737
> URL: https://issues.apache.org/jira/browse/SOLR-15737
> Project: Solr
> Issue Type: Improvement
> Components: v2 API
> Reporter: Jason Gerlowski
> Priority: Major
> Labels: V2
>
> Nothing in Solr's build system enforced consistency across v1<->v2, so as a
> result today, many v1 APIs (or API sub-commands) have no v2 counterpart. In
> some rare cases this was intentional (e.g.
> \{{/solr/admin/collections?action=MIGRATESTATEFORMAT}} ), but in most cases
> it's the result of unintentional omission.
> This ticket aims to remedying this, by finding v1 APIs without a v2
> counterpart and adding them where desired.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
