SOLR-16825: Migrate v2 API definitions to 'api' module, pt 9

solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionBackupApi.java

@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.client.api.endpoint;
+
+import io.swagger.v3.oas.annotations.Operation;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import org.apache.solr.client.api.model.CreateCollectionBackupRequestBody;
+import org.apache.solr.client.api.model.RestoreCollectionRequestBody;
+import org.apache.solr.client.api.model.SolrJerseyResponse;
+import org.apache.solr.client.api.model.SubResponseAccumulatingJerseyResponse;
+
+/**
+ * V2 API definition for creating a new "backup" of a specified collection
+ *
+ * <p>This API is analogous to the v1 /admin/collections?action=BACKUP command.
+ */
+public interface CollectionBackupApi {
+
+  @Path("/collections/{collectionName}/backups/{backupName}/versions")
+  interface Create {
+    @POST
+    @Operation(
+        summary = "Creates a new backup point for a collection",
+        tags = {"collection-backups"})
+    SolrJerseyResponse createCollectionBackup(
+        @PathParam("collectionName") String collectionName,
+        @PathParam("backupName") String backupName,
+        CreateCollectionBackupRequestBody requestBody)
+        throws Exception;
+  }
+
+  @Path("/backups/{backupName}/restore")
+  interface Restore {
+    @POST
+    @Operation(
+        summary = "Restores an existing backup point to a (potentially new) collection.",
+        tags = {"collection-backups"})
+    SubResponseAccumulatingJerseyResponse restoreCollection(
+        @PathParam("backupName") String backupName, RestoreCollectionRequestBody requestBody)
+        throws Exception;
+  }
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionSnapshotApis.java

@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.client.api.endpoint;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
+import org.apache.solr.client.api.model.CreateCollectionSnapshotRequestBody;
+import org.apache.solr.client.api.model.CreateCollectionSnapshotResponse;
+import org.apache.solr.client.api.model.DeleteCollectionSnapshotResponse;
+import org.apache.solr.client.api.model.ListCollectionSnapshotsResponse;
+
+/** V2 API definitions for creating, accessing, and deleting collection-level snapshots. */
+public interface CollectionSnapshotApis {
+
+  @Path("/collections/{collName}/snapshots")
+  interface Create {
+    @POST
+    @Path("/{snapshotName}")
+    @Operation(
+        summary = "Creates a new snapshot of the specified collection.",
+        tags = {"collection-snapshots"})
+    CreateCollectionSnapshotResponse createCollectionSnapshot(
+        @Parameter(description = "The name of the collection.", required = true)
+            @PathParam("collName")
+            String collName,
+        @Parameter(description = "The name of the snapshot to be created.", required = true)
+            @PathParam("snapshotName")
+            String snapshotName,
+        @RequestBody(description = "Contains user provided parameters", required = true)
+            CreateCollectionSnapshotRequestBody requestBody)
+        throws Exception;
+  }
+
+  @Path("/collections/{collName}/snapshots/{snapshotName}")
+  interface Delete {
+    @DELETE
+    @Operation(
+        summary = "Delete an existing collection-snapshot by name.",
+        tags = {"collection-snapshots"})
+    DeleteCollectionSnapshotResponse deleteCollectionSnapshot(
+        @Parameter(description = "The name of the collection.", required = true)
+            @PathParam("collName")
+            String collName,
+        @Parameter(description = "The name of the snapshot to be deleted.", required = true)
+            @PathParam("snapshotName")
+            String snapshotName,
+        @Parameter(description = "A flag that treats the collName parameter as a collection alias.")
+            @DefaultValue("false")
+            @QueryParam("followAliases")
+            boolean followAliases,
+        @QueryParam("async") String asyncId)
+        throws Exception;
+  }
+
+  @Path("/collections/{collName}/snapshots")
+  interface List {
+    @GET
+    @Operation(
+        summary = "List the snapshots available for a specified collection.",
+        tags = {"collection-snapshots"})
+    ListCollectionSnapshotsResponse listSnapshots(
+        @Parameter(description = "The name of the collection.", required = true)
+            @PathParam("collName")
+            String collName)
+        throws Exception;
+  }
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/CreateCollectionBackupApi.java → solr/api/src/java/org/apache/solr/client/api/endpoint/ReplicationBackupApis.java

@@ -17,27 +17,27 @@
 package org.apache.solr.client.api.endpoint;
 
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
-import jakarta.ws.rs.PathParam;
-import org.apache.solr.client.api.model.CreateCollectionBackupRequestBody;
-import org.apache.solr.client.api.model.SolrJerseyResponse;
+import org.apache.solr.client.api.model.ReplicationBackupRequestBody;
+import org.apache.solr.client.api.model.ReplicationBackupResponse;
+import org.apache.solr.client.api.util.CoreApiParameters;
 
 /**
- * V2 API definition for creating a new "backup" of a specified collection
+ * V2 endpoint for Backup API used for User-Managed clusters and Single-Node Installation.
  *
- * <p>This API is analogous to the v1 /admin/collections?action=BACKUP command.
+ * @see ReplicationApis
  */
-@Path("/collections/{collectionName}/backups/{backupName}/versions")
-public interface CreateCollectionBackupApi {
+@Path("/cores/{coreName}/replication")
+public interface ReplicationBackupApis {
 
   @POST
+  @CoreApiParameters
+  @Path("/backups")
   @Operation(
-      summary = "Creates a new backup point for a collection",
-      tags = {"collection-backups"})
-  SolrJerseyResponse createCollectionBackup(
-      @PathParam("collectionName") String collectionName,
-      @PathParam("backupName") String backupName,
-      CreateCollectionBackupRequestBody requestBody)
-      throws Exception;
+      summary = "Create a backup of a single core using Solr's 'Replication Handler'",
+      tags = {"replication-backups"})
+  ReplicationBackupResponse createBackup(
+      @RequestBody ReplicationBackupRequestBody backupReplicationPayload);
 }

solr/api/src/java/org/apache/solr/client/api/endpoint/ZooKeeperReadApis.java

@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.client.api.endpoint;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import org.apache.solr.client.api.model.ZooKeeperFileResponse;
+import org.apache.solr.client.api.model.ZooKeeperListChildrenResponse;
+
+/** V2 API definitions for Solr's ZooKeeper ready-proxy endpoint */
+@Path("/cluster/zookeeper/")
+public interface ZooKeeperReadApis {
+
+  @GET
+  @Path("/data{zkPath:.+}")
+  @Operation(
+      summary = "Return the data stored in a specified ZooKeeper node",
+      tags = {"zookeeper-read"})
+  @Produces({"application/vnd.apache.solr.raw", MediaType.APPLICATION_JSON})
+  ZooKeeperFileResponse readNode(
+      @Parameter(description = "The path of the node to read from ZooKeeper") @PathParam("zkPath")
+          String zkPath);
+
+  // The 'Operation' annotation is omitted intentionally here to ensure this API isn't picked up in
+  // the OpenAPI spec and consequent code-generation.  The server side needs this method to be
+  // different from 'readNode' above for security reasons (more privileges are needed to access
+  // security.json), but it's the same logical API expressed by the 'readNode' signature above.
+  @GET
+  @Path("/data/security.json")
+  @Produces({"application/vnd.apache.solr.raw", MediaType.APPLICATION_JSON})
+  ZooKeeperFileResponse readSecurityJsonNode();
+
+  @GET
+  @Path("/children{zkPath:.*}")
+  @Produces({"application/json", "application/javabin"})
+  @Operation(
+      summary = "List and stat all children of a specified ZooKeeper node",
+      tags = {"zookeeper-read"})
+  ZooKeeperListChildrenResponse listNodes(
+      @Parameter(description = "The path of the ZooKeeper node to stat and list children of")
+          @PathParam("zkPath")
+          String zkPath,
+      @Parameter(
+              description =
+                  "Controls whether stat information for child nodes is included in the response. 'true' by default.")
+          @QueryParam("children")
+          Boolean includeChildren)
+      throws Exception;
+}

solr/api/src/java/org/apache/solr/client/api/model/DeleteCollectionSnapshotResponse.java

@@ -21,12 +21,8 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
-import org.apache.solr.client.api.endpoint.DeleteCollectionSnapshotApi;
 
-/**
- * The Response for {@link DeleteCollectionSnapshotApi#deleteCollectionSnapshot(String, String,
- * boolean, String)}
- */
+/** The Response for {@link org.apache.solr.client.api.endpoint.CollectionSnapshotApis.Delete} */
 public class DeleteCollectionSnapshotResponse extends AsyncJerseyResponse {
   @Schema(description = "The name of the collection.")
   @JsonProperty(COLLECTION)

solr/core/src/java/org/apache/solr/jersey/ExperimentalResponse.java → solr/api/src/java/org/apache/solr/client/api/model/ExperimentalResponse.java

@@ -15,10 +15,9 @@
  * limitations under the License.
  */
 
-package org.apache.solr.jersey;
+package org.apache.solr.client.api.model;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
-import org.apache.solr.client.api.model.SolrJerseyResponse;
 
 /**
  * {@link SolrJerseyResponse} implementation with a warning field indicating that the format may