[
https://issues.apache.org/jira/browse/SOLR-15737?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17617806#comment-17617806
]
Jason Gerlowski edited comment on SOLR-15737 at 10/14/22 4:26 PM:
------------------------------------------------------------------
The v2 API code has changed a good bit since the "Step-by-Step" I wrote in
July, so it makes sense to update that here, especially with some of the new
interest in these tickets. (I'm sorry for not posting this sooner!)
In particular, we've added a new framework for implementing v2 APIs, to
supplement the existing one. Both the old framework described in my earlier
comment and the new framework (described below) work well and are supported -
so code written in either framework is fine. But the new v2 API framework
improves on the old in a few ways, so it should probably be preferred going
forward.
h3. Why the new Framework?
The new framework relies on annotations from a public standard called "JAX-RS"
(and its reference implementation, "Jersey"). JAX-RS/Jersey are used by many
projects to define their APIs in a uniform way, and as such are familiar to a
wider pool of developers. Over time, a lot of tooling (e.g. Swagger, OpenAPI)
has built up around this format as well which Solr will be able to take
advantage of as APIs are added or converted over to the new framework.
See SOLR-16347 for more details.
h3. What Differs in the New API Framework?
The new framework is similar to the old in many ways: APIs are still defined in
"API" classes, using annotations to define the path, HTTP verb, etc. APIs are
also still "registered" by connecting them with an existing RequestHandler (see
the {{getJerseyResources}} method).
That said, there are some difference. The biggest ones are:
# The new framework uses annotations defined in the JAX-RS spec (e.g.
{{@Path}}, {{@GET}}), instead of the {{@Endpoint}}, {{@Command}}, etc.
annotations used by the original v2 framework.
# API inputs and outputs are specified differently in the JAX-RS framework.
Where methods in the old v2 framework could either take a
SolrQueryRequest/SolrQueryResponse pair, or a Payload>, JAX-RS API methods can
have flexible signatures, with a method argument for each query-parameter,
path-parameter, etc. Additionally, in JAX-RS, API methods can have a non-void
return value to represent the response back to the user. (See
[here|https://github.com/apache/solr/blob/ddb2b94e7607bcb365224056438e8acafcd5e00b/solr/core/src/java/org/apache/solr/handler/configsets/ListConfigSetsAPI.java#L65]
for an example).
# While JAX-RS APIs _can_ still be written to reformat their inputs and call
into the existing v1 RequestHandler code, that pattern can be reversed as well.
That is, for some APIs, it makes sense to move the real functionality into the
v2 API code itself, and change the v1 RequestHandler code to call into the v2
code. (This approach positions Solr better down the line for an eventual
removal of the v1 APIs...in addition to some less-important but more immediate
benefits.)
For those familiar with the existing v2 framework, these changes can sound
daunting, but in practice they tend to be intuitive most of the time. (Fingers
crossed!)
[AddReplicaPropertyAPI|https://github.com/apache/solr/blob/a1ee7c1d0de32779109cb8b66a4319a0f8c85037/solr/core/src/java/org/apache/solr/handler/admin/api/AddReplicaPropertyAPI.java#L75]
is a great, non-trivial example of an API written using the newer JAX-RS
framework.
I hope to post a "step-by-step" shortly that describes how to use the JAX-RS
framework to create an API from scratch, similar to my comment above for the
original v2 framework. But hopefully the description and pointer to
AddReplicaPropertyAPI example can serve as a decent stopgap until then for
anyone willing to give it a shot!
was (Author: gerlowskija):
The v2 API code has changed a good bit since the "Step-by-Step" I wrote in
July, so it makes sense to update that here, especially with some of the new
interest in these tickets. (I'm sorry for not posting this sooner!)
In particular, we've added a new framework for implementing v2 APIs, to
supplement the existing one. Both the old framework described in my earlier
comment and the new framework (described below) work well and are supported -
so code written in either framework is fine. But the new v2 API framework
improves on the old in a few ways, so it should probably be preferred going
forward.
h3. Why the new Framework?
The new framework relies on annotations from a public standard called "JAX-RS"
(and its reference implementation, "Jersey"). JAX-RS/Jersey are used by many
projects to define their APIs in a uniform way, and as such are familiar to a
wider pool of developers. Over time, a lot of tooling (e.g. Swagger, OpenAPI)
has built up around this format as well which Solr will be able to take
advantage of as APIs are added or converted over to the new framework.
See SOLR-16347 for more details.
h3. What Differs in the New API Framework?
The new framework is similar to the old in many ways: APIs are still defined in
"API" classes, using annotations to define the path, HTTP verb, etc. APIs are
also still "registered" by connecting them with an existing RequestHandler (see
the {{getJerseyResources}} method).
That said, there are some difference. The biggest ones are:
# The new framework uses annotations defined in the JAX-RS spec (e.g.
{{@Path}}, {{@GET}}), instead of the {{@Endpoint}}, {{@Command}}, etc.
annotations used by the original v2 framework.
# API inputs and outputs are specified differently in the JAX-RS framework.
Where methods in the old v2 framework could either take a
SolrQueryRequest/SolrQueryResponse pair, or a Payload>, JAX-RS API methods can
have flexible signatures, with a method argument for each query-parameter,
path-parameter, etc. Additionally, in JAX-RS, API methods can have a non-void
return value to indicate the response back to the user. (See here for an
example).
# While JAX-RS APIs _can_ still be written to reformat their inputs and call
into the existing v1 RequestHandler code, that pattern can be reversed as well.
That is, for some APIs, it makes sense to move the real functionality into the
v2 API code itself, and change the v1 RequestHandler code to call into the v2
code. (This approach positions Solr better down the line for an eventual
removal of the v1 APIs...in addition to some less-important but more immediate
benefits.)
For those familiar with the existing v2 framework, these changes can sound
daunting, but in practice they tend to be intuitive most of the time. (Fingers
crossed!)
[AddReplicaPropertyAPI|https://github.com/apache/solr/blob/a1ee7c1d0de32779109cb8b66a4319a0f8c85037/solr/core/src/java/org/apache/solr/handler/admin/api/AddReplicaPropertyAPI.java#L75]
is a great, non-trivial example of an API written using the newer JAX-RS
framework.
I hope to post a "step-by-step" shortly that describes how to use the JAX-RS
framework to create an API from scratch, similar to my comment above for the
original v2 framework. But hopefully the description and pointer to
AddReplicaPropertyAPI example can serve as a decent stopgap until then for
anyone willing to give it a shot!
> 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, newdev
>
> 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
