Hey Christos,
Thanks for raising this!
> without having worked on the API before and without participating in any
> prior discussions
Quick summary of past discussions and decisions - not defending them
necessarily, but important context:
'/api/node' is reserved for APIs that only impact the receiving node
(and aren't otherwise proxied or distributed): node-healthcheck,
status-checking on node-level asynchronous operations, fetching
node-specific info (like the node's public-key, environment variables,
etc.), debug operations like triggering a thread-dump. '/api/cluster'
has APIs that are only available in "SolrCloud" mode, and that
(secondarily) have to do with cluster topology/state: cluster
properties, setting node-roles, cross-node rebalancing, package and
filestore operations, etc.
That's not to say that we've gotta stick with those semantics; if
there's consensus in another direction we should act while v2 is still
"experimental".
> What prevents us from moving towards that direction?
I love these API suggestions, from a purely aesthetic/cosmetic
perspective. But there are some obstacles IMO - the biggest one being
limitations in Solr's featureset as it stands today.
Take "cluster properties" and "node roles" as examples. I agree that
it'd be great to offer them in standalone as well as SolrCloud, and to
change the API path to suit. But that'd be a massive effort, and
while those gaps exist removing the "/cluster" bit of the path might
mislead as many users as it helps.
Best,
Jason
On Fri, Feb 14, 2025 at 12:15 PM Christos Malliaridis
<malliari...@apache.org> wrote:
>
> Hello everyone,
>
> I am looking into the v2 API and I was wondering what our final design will
> look like in terms of single- and multi-node setups.
>
> The main question I am trying to answer for myself is "Do we need to
> distinguish between the operation mode at API endpoints"?
>
> From what I can see in the API proposals and current state, some API
> endpoints operate inside a cluster context (like /api/cluster/properties),
> some inside a node context (like /api/node/logging), some other in cluster
> node context (like /api/cluster/nodes/{nodeName}/roles), and some in no
> context (which is I believe cluster and node, depending on operation mode?,
> like in /api/aliases/{aliasName}/properties).
>
> From a consumer's point of view, this may be a bit irritating, and without
> having worked on the API before and without participating in any prior
> discussions, I would believe that it could be simplified.
>
> Looking into where we are now and what we may expect from Solr in the
> future, we may not have to distinguish between the operation modes at the
> API endpoints. I am not aware of the historical background or any
> constraints that probably apply, so please educate me.
>
> From what little I know, the following changes would make sense to me:
> - GET /api/cluster/properties could be just GET /api/properties
> - it would get the properties of Solr. If it is a cluster, whether it is
> a single node or multiple, it should not make a difference
> - GET /api/node/logging/messages could be
> /api/nodes/{nodeId}/logging/messages
> - It would get the log messages of a specific node. For single node
> setups, the node ID is always the same, for multi-nodes it would have
> different node IDs
> - PUT /api/logging/levels could be added to reflect a cluster-wide log
> level configuration, which seems to be missing in the v2 API at the moment
> of writing
> - GET /api/cluster/nodes/{nodeId}/roles could be /api/nodes/{nodeName}/roles
> - it would return the roles of a specific node (if the roles are per node
> configured)
> - GET /api/aliases/{aliasName}/properties would stay as is, as it is
> node-independent and therefore a nice and simple endpoint
>
> This way we would reduce the complexity of our API (for the consumers) and
> make it more intuitive. Additionally, the consumers would not need to know
> whether there are multiple nodes or a single node running Solr, and will
> always have a "collection of nodes", even if that collection contains only
> a single node at times. And when scaling from one node to multiple nodes,
> no changes at the consumer's side are required (which I'm not sure if this
> is currently the case).
>
> What prevents us from moving towards that direction?
>
> Best,
> Christos
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@solr.apache.org
For additional commands, e-mail: dev-h...@solr.apache.org
