[ 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: issues-unsubscr...@solr.apache.org For additional commands, e-mail: issues-h...@solr.apache.org