I can provide examples for the two use cases of the solr-operator (I hope
you were referring to these).
Let's take this use case:
1. getReplicasForPod (controllers/solr_cluster_ops_util.go:701) — called
> from evictSinglePod during a managed scale-down. Fetches full CLUSTERSTATUS
> (no collection param), walks every collection/shard/replica looking for any
> replica whose node_name matches the pod being evicted, to determine whether
> the pod is safe to terminate.
So we want to get all replicas which belong to a node that matches the name
of the pod being evicted. Given the name of the pod, we have two options:
Option 1: replicas are a top level resource
That means we have /api/replicas, and we can simply filter replicas by
node. Each replica has to know here to which node it belongs. That would
allow us to call
GET /api/replicas?node={pod_name}
Option 2: replicas are sub-resources of nodes
It is not required that replicas are sub-resources of nodes only, they can
also be sub-resources of shards, or collections, depending on what use
cases we have. Here, most useful would be if we have
/api/nodes/{node_id}/replicas. So a call for getting the replicas would be:
GET /api/nodes/{pod_name}/replicas
For the second scenario we have
2. GetNodeReplicaState (controllers/util/solr_update_util.go:124) — called
> from handleManagedCloudRollingUpdate during a managed rolling update.
> Fetches full CLUSTERSTATUS plus a separate OVERSEERSTATUS call, aggregates
> per-node leader/replica/active-shard counts via findSolrNodeContents, and
> feeds DeterminePodsSafeToUpdate's decision about which out-of-date pod to
> restart next.
This one is a bit harder to break down, as it calls and psses the cluster
status to multiple functions. But from what I could find with a quick
lookup is that we are basically interested only in the replicas, replicas
counts, and eventually the information of nodes. So with a wild guess, I
would say that we could likely cover these cases with two endpoints that
have other usages as well:
- GET /api/nodes eventually with additional query params
- GET /api/replicas, eventually with node as query param (as in use case
1). The endpoint GET /api/nodes/{node}/replicas may also be of use here,
depending on if we want to look at each node's replicas one by one.
Both solutions would benefit from the endpoint /api/nodes with a query
parameter for its state, like GET
/api/nodes?state=offline,not_started,unknown (or whatever states we have
and are interested in).
Not sure if I addressed the right use cases and if that adds some
clarification to the resources here Jason.
On Thu, Sep 24, 2026 at 4:41 PM Jason Gerlowski <[email protected]>
wrote:
> Hey Christos,
>
> Do you have a particular division or set of endpoints in mind that
> you'd recommend?
>
> The tension I'm struggling with here is the difference between the
> design that's the most "REST-ful" and the one that's the most useful.
> Those seem to be at odds here. CLUSTERSTATUS is an ugly,
> mega-endpoint that returns way too much information....but if you look
> at its callers they tend to want/need all that information. They're
> making bounce or replica placement decisions that require knowing the
> status of...well, the whole cluster. We can decompose the endpoint,
> but if the result is that callers would now need to make 10 or 20 or
> 100 API calls (as in epugh's example above) it's a worse experience
> for them.
>
> It seems like you're suggesting that conflict is avoidable with the
> right resource definitions or endpoints, but I'm having trouble seeing
> what you have in mind. Could you give a bit more detail please?
>
> Best,
>
> Jason
>
> On Tue, Sep 22, 2026 at 7:37 AM Christos Malliaridis
> <[email protected]> wrote:
> >
> > Sorry for entering the discussion so late with my two cents below, but
> perhaps I can add some more insights from a consumer's perspective and help
> answer the question "to what direction should we head with v2 API".
> >
> > In a previous discussion a couple months ago, Jason and I were talking
> about "REST"ful APIs, mainly from a consumer's perspective, but also for
> determining the API endpoints. We were trying to define what the structure
> of the API endpoints should be, and what data should be provided by each
> endpoint, with the goal to also avoid duplicated data across endpoints.
> >
> > In a RESTful API, we are normally talking about resources. The v2
> proposal page in the spreadsheet [1] was aiming for defining the resources
> we have in Solr at API level, without being influenced from internal
> structure or implementation details.
> >
> > Taking the discussion's outcome, /api/cluster would fetch a single
> resource element, the cluster, and provide information about the cluster.
> Not the nodes, not the shards, not collections. If we are interested in
> nodes, we would use the resource collection GET /api/nodes, optionally with
> some query parameters like status=healthy.
> >
> > By focusing on what a resource is and what information it carries
> (scoped), we would avoid super-endpoints that provide too much information,
> like the CLUSTERSTATUS does right now.
> >
> > The new Admin UI is also applying the concept of resources in the
> designs. I am not sure if we want to follow that ideology, but it could
> definitely help against excessive data exposure from single endpoints. The
> SOLID principles would also take effect in various ways.
> >
> > [1]
> https://docs.google.com/spreadsheets/d/1HAoBBFPpSiT8mJmgNZKkZAPwfCfPvlc08m5jz3fQBpA/edit?pli=1&gid=1878317994#gid=1878317994
> >
> > On 2026/09/08 11:19:26 Eric Pugh wrote:
> > > Hi all, spelunking a bit through what API to convert from our old
> homegrown V2 and to the Jax RS V2 approach, and I noticed that
> CLUSTERSTATUS is one that is used to drive a lot of our Admin UI. So I
> thought, hey, that will be an easy migration.
> > >
> > > I found this closed (but not merged) PR:
> https://github.com/apache/solr/pull/2670 from David, and this JIRA
> https://issues.apache.org/jira/browse/SOLR-17422.
> > >
> > > Before I go down the path of making some more JIRAs for various V2 api
> work for folks to pick up, at least for CLUSTERSTATUS, I wanted to see if
> anyone had sketched out what we WANT the API structure to look like?
> > >
> > > I had a comment from two years ago on this, but hadn’t done anything
> about it…..
> > >
> > > Eric
> > >
> > > Disclaimer
> > >
> > > The information contained in this communication from the sender is
> confidential. It is intended solely for use by the recipient and others
> authorized to receive it. If you are not the recipient, you are hereby
> notified that any disclosure, copying, distribution or taking action in
> relation of the contents of this information is strictly prohibited and may
> be unlawful.
> > >
> > > This email has been scanned for viruses and malware, and may have been
> automatically archived by Mimecast, a leader in email security and cyber
> resilience. Mimecast integrates email defenses with brand protection,
> security awareness training, web security, compliance and other essential
> capabilities. Mimecast helps protect large and small organizations from
> malicious activity, human error and technology failure; and to lead the
> movement toward building a more resilient world. To find out more, visit
> our website.
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [email protected]
> > For additional commands, e-mail: [email protected]
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
>
