Update links for Control Plane and Data Plane API references (#185)

* Update xrefs for control plane and data plane * Add reference split to what's new * Improve index descriptions * Apply suggestions from review * Apply edit from review * Apply suggestions from code review Co-authored-by: Angela Simms <[email protected]> * Move API reference split update to new Feb 25 section * Apply suggestions from code review --------- Co-authored-by: Angela Simms <[email protected]>
redpanda-data · Feb 3, 2025 · d2aa19f · d2aa19f
1 parent 486baea
commit d2aa19f
Show file tree

Hide file tree

Showing 24 changed files with 105 additions and 94 deletions.
diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml
@@ -15,7 +15,7 @@ content:
   - url: .
     branches: HEAD
   - url: https://github.com/redpanda-data/documentation
-    branches: [main, v/*, 'DOC-773-single-source-leader-pinning', api, shared, site-search]
+    branches: [main, v/*, api, shared, site-search]
   - url: https://github.com/redpanda-data/redpanda-labs
     branches: main
     start_paths: [docs,'*/docs']

diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
@@ -388,7 +388,8 @@
 *** xref:reference:tiers/byoc-tiers.adoc[]
 *** xref:reference:tiers/dedicated-tiers.adoc[]
 ** xref:reference:api-reference.adoc[]
-*** xref:api:ROOT:cloud-api.adoc[]
+*** xref:api:ROOT:cloud-controlplane-api.adoc[]
+*** xref:api:ROOT:cloud-dataplane-api.adoc[]
 *** xref:api:ROOT:pandaproxy-rest.adoc[]
 *** xref:api:ROOT:pandaproxy-schema-registry.adoc[]
 ** xref:reference:rpk/index.adoc[rpk Commands]

diff --git a/modules/develop/pages/connect/about.adoc b/modules/develop/pages/connect/about.adoc
@@ -1,5 +1,5 @@
 = Redpanda Connect in Redpanda Cloud
-:tag-pipeline-service: api:ROOT:cloud-api.adoc#tag--PipelineService
+:tag-pipeline-service: api:ROOT:cloud-dataplane-api.adoc#tag--PipelineService
 :description: Learn about Redpanda Connect in Redpanda Cloud and its wide range of connectors.
 
 include::develop:partial$availability-message.adoc[]

diff --git a/modules/develop/pages/connect/configuration/resource-management.adoc b/modules/develop/pages/connect/configuration/resource-management.adoc
@@ -135,7 +135,7 @@ Data Plane API::
 +
 --
 . xref:manage:api/cloud-api-quickstart.adoc#try-the-cloud-api[Authenticate and get the base URL] for the Data Plane API. 
-. Make a request to xref:api:ROOT:cloud-api.adoc#get-/v1alpha2/redpanda-connect/pipelines[`GET /v1alpha2/redpanda-connect/pipelines`], which lists details of all pipelines on your cluster by ID. 
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#get-/v1alpha2/redpanda-connect/pipelines[`GET /v1alpha2/redpanda-connect/pipelines`], which lists details of all pipelines on your cluster by ID. 
 +
 * Memory (`memory_shares`) is displayed in megabytes. For example, `1` task is `400M` or 400 MB.
 * CPU resources (`cpu_shares`) are displayed milliCPU. For example, `1` task is `100m` or 0.1 CPU.
@@ -163,8 +163,8 @@ Data Plane API::
 You can only update CPU resources using the Data Plane API. For every 0.1 CPU that you allocate, Redpanda Cloud automatically reserves 400 MB of memory for the exclusive use of the pipeline.
 
 . xref:manage:api/cloud-api-quickstart.adoc#try-the-cloud-api[Authenticate and get the base URL] for the Data Plane API, if you haven't already.
-. Make a request to xref:api:ROOT:cloud-api.adoc#get-/v1alpha2/redpanda-connect/pipelines/-id-[`GET /v1alpha2/redpanda-connect/pipelines/\{id}`], including the ID of the pipeline you want to update. You'll use the returned values in the next step.
-. Now make a request to xref:api:ROOT:cloud-api.adoc#put-/v1alpha2/redpanda-connect/pipelines/-id-[`PUT /v1alpha2/redpanda-connect/pipelines/\{id}`], to update the pipeline resources:
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#get-/v1alpha2/redpanda-connect/pipelines/-id-[`GET /v1alpha2/redpanda-connect/pipelines/\{id}`], including the ID of the pipeline you want to update. You'll use the returned values in the next step.
+. Now make a request to xref:api:ROOT:cloud-dataplane-api.adoc#put-/v1alpha2/redpanda-connect/pipelines/-id-[`PUT /v1alpha2/redpanda-connect/pipelines/\{id}`], to update the pipeline resources:
 +
 * Reuse the values returned by your `GET` request to populate the request body. 
 * Replace the `cpu_shares` value with the resources you want to allocate, and enter any valid value for `memory_shares`.
@@ -188,6 +188,6 @@ curl -X PUT "https://<data-plane-api-url>/v1alpha2/redpanda-connect/pipelines/xx
 ----
 +
 A successful response shows the updated resource allocations with the `cpu_shares` value returned in milliCPU.
-. Make a request to xref:api:ROOT:cloud-api.adoc#get-/v1alpha2/redpanda-connect/pipelines[`GET /v1alpha2/redpanda-connect/pipelines`] to verify your pipeline resource updates.
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#get-/v1alpha2/redpanda-connect/pipelines[`GET /v1alpha2/redpanda-connect/pipelines`] to verify your pipeline resource updates.
 --
 =====
diff --git a/modules/develop/pages/connect/configuration/secret-management.adoc b/modules/develop/pages/connect/configuration/secret-management.adoc
@@ -62,7 +62,7 @@ Data Plane API::
 You must use a Base64-encoded secret.
 
 . xref:manage:api/cloud-api-quickstart.adoc#try-the-cloud-api[Authenticate and get the base URL] for the Data Plane API.
-. Make a request to xref:api:ROOT:cloud-api.adoc#post-/v1alpha2/secrets[`POST /v1alpha2/secrets`].
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#post-/v1alpha2/secrets[`POST /v1alpha2/secrets`].
 +
 [,bash]
 ----
@@ -127,7 +127,7 @@ Data Plane API::
 You must use a Base64-encoded secret.
 
 . xref:manage:api/cloud-api-quickstart.adoc#try-the-cloud-api[Authenticate and get the base URL] for the Data Plane API.
-. Make a request to xref:api:ROOT:cloud-api.adoc#put-/v1alpha2/secrets/-id-[`PUT /v1alpha2/secrets/\{id}`].
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#put-/v1alpha2/secrets/-id-[`PUT /v1alpha2/secrets/\{id}`].
 +
 [,bash]
 ----
@@ -188,7 +188,7 @@ Data Plane API::
 --
 
 . xref:manage:api/cloud-api-quickstart.adoc#try-the-cloud-api[Authenticate and get the base URL] for the Data Plane API.
-. Make a request to xref:api:ROOT:cloud-api.adoc#delete-/v1alpha2/secrets/-id-[`DELETE /v1alpha2/secrets/\{id}`].
+. Make a request to xref:api:ROOT:cloud-dataplane-api.adoc#delete-/v1alpha2/secrets/-id-[`DELETE /v1alpha2/secrets/\{id}`].
 +
 [,bash]
 ----

diff --git a/modules/get-started/pages/cloud-overview.adoc b/modules/get-started/pages/cloud-overview.adoc
@@ -1,7 +1,7 @@
 = Redpanda Cloud Overview
 :description: Learn about Redpanda Serverless Standard, Serverless Pro, Dedicated, and Bring Your Own Cloud (BYOC) clusters.
 :description: Learn about Redpanda Serverless, Dedicated, and Bring Your Own Cloud (BYOC) clusters.
-:tag-pipeline-service: api:ROOT:cloud-api.adoc#tag--PipelineService
+:tag-pipeline-service: api:ROOT:cloud-dataplane-api.adoc#tag--PipelineService
 :page-aliases: cloud:dedicated-byoc.adoc, deploy:deployment-option/cloud/dedicated-byoc.adoc, deploy:deployment-option/cloud/cloud-overview.adoc
 
 

diff --git a/modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc b/modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc
@@ -20,7 +20,7 @@ The https://github.com/redpanda-data/cloud-examples/tree/main/customer-managed/a
 
 * Access to an AWS project in which you create your cluster.
 * Minimum permissions in that AWS project. For the actions required by the user who will create the cluster with `rpk cloud byoc aws apply`, see https://github.com/redpanda-data/cloud-examples/blob/main/customer-managed/aws/terraform/iam_rpk_user.tf[`iam_rpk_user.tf`^].
-* Familiarity with the xref:api:ROOT:cloud-api.adoc[Redpanda Cloud API]. For example, you should be familiar with how to use the Cloud API to authenticate and create a cluster.
+* Familiarity with the Redpanda Cloud API. For example, you should be familiar with how to use the Cloud API to xref:redpanda-cloud:manage:api/cloud-api-authentication.adoc[authenticate] and xref:redpanda-cloud:manage:api/controlplane/index.adoc[create a cluster.
 * https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli[Terraform^] version 1.8.5 or later.
 
 == Limitations
@@ -192,7 +192,7 @@ export REDPANDA_VERSION=24.3
 export REDPANDA_THROUGHPUT_TIER=tier-1-aws-v3-arm
 ```
 +
-TIP: See the full list of zones and tiers available with each provider in the xref:api:ROOT:cloud-api.adoc#api-description[API reference].
+TIP: See the full list of zones and tiers available with each provider in the xref:api:ROOT:cloud-controlplane-api.adoc#api-description[Control Plane API reference].
 
 . Define a JSON file called `redpanda-cluster.json` that includes cluster information: 
 +

diff --git a/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc b/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
@@ -128,7 +128,7 @@ To enable xref:develop:managed-connectors/index.adoc[Kafka Connect] for clusters
 
 . Authenticate to the Redpanda Cloud API. Follow the steps in xref:manage:api/cloud-api-authentication.adoc[].
 
-. Enable Kafka Connect by making a xref:api:ROOT:cloud-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters`] request:
+. Enable Kafka Connect by making a xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters`] request:
 +
 [,bash]
 ----

diff --git a/modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc b/modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc
@@ -389,7 +389,7 @@ EOF
 ```
 ====
 +
-TIP: See the full list of zones and tiers available with each provider in the xref:api:ROOT:cloud-api.adoc#api-description[API reference].
+TIP: See the full list of zones and tiers available with each provider in the xref:api:ROOT:cloud-controlplane-api.adoc#api-description[Control Plane API reference].
 
 . Make a Cloud API call to create a Redpanda network and get the network ID from the response in JSON `.operation.metadata.network_id`.
 +

diff --git a/modules/get-started/pages/cluster-types/byoc/remote-read-replicas.adoc b/modules/get-started/pages/cluster-types/byoc/remote-read-replicas.adoc
@@ -51,9 +51,9 @@ This should be done in the Terraform of the reader cluster.
 
 == Configure remote read replica
 
-Add or remove reader clusters to a source cluster in Redpanda Cloud with the xref:api:ROOT:cloud-api.adoc[Cloud API]. For information on accessing the Cloud API, see xref:manage:api/cloud-api-authentication.adoc[].
+Add or remove reader clusters to a source cluster in Redpanda Cloud with the xref:redpanda-cloud:manage:api/controlplane/index.adoc[Cloud Control Plane API]. For information on accessing the Cloud API, see xref:manage:api/cloud-api-authentication.adoc[].
 
-. To update your source cluster to add one or more reader cluster IDs, make a xref:api:ROOT:cloud-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters/\{cluster.id}`] request. The full list of clusters is expected on every call. If an ID is removed from the list, it is removed as a reader cluster.
+. To update your source cluster to add one or more reader cluster IDs, make a xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters/{cluster.id}`] request. The full list of clusters is expected on every call. If an ID is removed from the list, it is removed as a reader cluster.
 +
 ```bash
 export SOURCE_CLUSTER_ID=.......
@@ -69,7 +69,7 @@ curl -X PATCH $API_HOST/v1beta2/clusters/$SOURCE_CLUSTER_ID \
 EOF
 ```
 
-. Optional: To see the list of reader clusters on a given source cluster, make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`] request:
+. Optional: To see the list of reader clusters on a given source cluster, make a xref:api:ROOT:cloud-controlplane-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`] request:
 +
 ```bash
 export SOURCE_CLUSTER_ID=.......

diff --git a/modules/get-started/pages/whats-new-cloud.adoc b/modules/get-started/pages/whats-new-cloud.adoc
@@ -1,12 +1,18 @@
 = What's New in Redpanda Cloud
 :description: Summary of new features in Redpanada Cloud.
-:tag-pipeline-service: api:ROOT:cloud-api.adoc#tag--PipelineService
+:tag-pipeline-service: api:ROOT:cloud-dataplane-api.adoc#tag--PipelineService
 :page-aliases: deploy:deployment-option/cloud/whats-new-cloud.adoc
 :page-toclevels: 1
 
 
 This page lists new features added in Redpanda Cloud.
 
+== February 2025
+
+=== Cloud API reference
+
+The Cloud API reference is now provided as separate references for the xref:api:ROOT:cloud-controlplane-api.adoc[Control Plane API] and xref:api:ROOT:cloud-dataplane-api.adoc[Data Plane APIs]. The Control Plane API and Data Plane APIs follow separate OpenAPI specifications, so the reference is updated to better reflect the structure of the Cloud APIs and to improve usability of the documentation. See also: xref:manage:api/cloud-api-overview.adoc[].
+
 == January 2025
 
 === New tiers and regions on Azure
@@ -128,7 +134,7 @@ Redpanda has increased the number of client connections in all xref:reference:ti
 
 === Cloud API: beta
 
-The Cloud API allows you to programmatically manage clusters and resources in your Redpanda Cloud organization. For more information, see the xref:manage:api/cloud-api-quickstart.adoc[Cloud API Quickstart], the xref:manage:api/cloud-api-overview.adoc[Cloud API Overview], and the full xref:api:ROOT:cloud-api.adoc[Cloud API reference].
+The Cloud API allows you to programmatically manage clusters and resources in your Redpanda Cloud organization. For more information, see the xref:manage:api/cloud-api-quickstart.adoc[Cloud API Quickstart], the xref:manage:api/cloud-api-overview.adoc[Cloud API Overview], and the full xref:api:ROOT:cloud-controlplane-api.adoc[Control Plane API] and xref:api:ROOT:cloud-dataplane-api.adoc[Data Plane API] reference documentation.
 
 === mTLS authentication for Kafka API clients
 

diff --git a/modules/manage/pages/api/cloud-api-overview.adoc b/modules/manage/pages/api/cloud-api-overview.adoc
@@ -25,7 +25,8 @@ The *Data Plane APIs* are a collection of APIs through which you can perform act
 
 See also:
 
-* xref:api:ROOT:cloud-api.adoc[Redpanda Cloud API reference]
+* xref:api:ROOT:cloud-controlplane-api.adoc[Control Plane API reference]
+* xref:api:ROOT:cloud-dataplane-api.adoc[Data Plane API reference]
 * xref:reference:api-reference.adoc[Redpanda API and SDK Reference documentation]
 
 == Base URLs

diff --git a/modules/manage/pages/api/cloud-api-quickstart.adoc b/modules/manage/pages/api/cloud-api-quickstart.adoc
@@ -14,9 +14,9 @@ BYOC or Dedicated::
 +
 --
 . In the Redpanda Cloud UI, create a https://cloud.redpanda.com/clients[service account (client)] and use the client ID and secret to request an API token. Use the token to xref:manage:api/cloud-api-authentication.adoc[authenticate to the API].
-. Create a resource group by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/resource-groups[`POST /v1beta2/resource-groups`] request.
-. Create a network by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`] request. Note that this operation may be long-running.
-. Create a cluster by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/clusters[`POST /v1beta2/clusters`] request.
+. Create a resource group by making a xref:api:ROOT:cloud-controlplane-api.adoc#post-/v1beta2/resource-groups[`POST /v1beta2/resource-groups`] request.
+. Create a network by making a xref:api:ROOT:cloud-controlplane-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`] request. Note that this operation may be long-running.
+. Create a cluster by making a xref:api:ROOT:cloud-controlplane-api.adoc#post-/v1beta2/clusters[`POST /v1beta2/clusters`] request.
 . For BYOC, run `rpk cloud byoc`, passing the `metadata.cluster_id` from the Create Cluster response as a flag:
 +
 AWS:
@@ -71,14 +71,14 @@ curl -H 'Content-Type: application/json' \
 
 == Try the Cloud API
 
-You can issue requests against the Cloud API from your browser when viewing the xref:api:ROOT:cloud-api.adoc[API reference]. 
+You can issue requests against the Cloud API from your browser when viewing the API reference. 
 
-Complete the following steps:
+On the Control Plane API or Data Plane API references, complete the following steps:
 
 . Go to *Authentication* in the sidebar.
 . Click *Get Token*.
 . If successful, the text “1 API key applied” displays under the *Authentication* section of this page. The token is valid for an hour.
-. Choose the correct API server for your request.
+. Choose the correct API server for your <<make-a-request-to-the-control-plane-api,Control Plane API>> or <<make-a-request-to-the-data-plane-apis,Data Plane API>> request.
 
 WARNING: Your API requests are executed against your actual environment and data, not a sandbox. 
 

diff --git a/modules/manage/pages/api/cloud-byoc-controlplane-api.adoc b/modules/manage/pages/api/cloud-byoc-controlplane-api.adoc
@@ -1,5 +1,5 @@
 = Use the Control Plane API with BYOC
-:description: Use the Control Plane API to manage resources in your Redpanda Cloud organization.
+:description: Use the Control Plane API to manage resources in your Redpanda Cloud BYOC environment.
 :page-aliases: deploy:deployment-option/cloud/api/cloud-controlplane-api.adoc
 :page-context-links: [{"name": "BYOC", "to": "manage:api/cloud-byoc-controlplane-api.adoc" },{"name": "Dedicated", "to": "manage:api/cloud-dedicated-controlplane-api.adoc" },{"name": "Serverless", "to": "manage:api/cloud-serverless-controlplane-api.adoc" } ]
 :page-beta: true
-Original file line number
+Diff line change
@@ Expand Up @@
     . Authenticate to the Redpanda Cloud API. Follow the steps in xref:manage:api/cloud-api-authentication.adoc[].
-    . Enable Kafka Connect by making a xref:api:ROOT:cloud-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters`] request:
+    . Enable Kafka Connect by making a xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1beta2/clusters/-cluster.id-[`PATCH /v1beta2/clusters`] request:
     +
     [,bash]
     ----
@@ Expand Down @@