Clean up Cloud API specs (#13)

* Remove Regions from Control Plane API info.description

* Change server.url for Data Plane API for Bump proxy

* Fill out info.description for Data Plane API

* Apply consistent sentence case to endpoint summaries

To follow our style guide and be consistent with the Cloud UI

* Review control plane quickstart

* Further cleanup of control plane quickstart

* Ensure data plane quickstart reflects one-click OAuth flow

* Minor edits

* Clean up old API reference URLs

* x-topic titles are already applied via overlay

* Typo

* Fix produce example

* File not included

Author: kbatuigas

cloud-controlplane/cloud-controlplane.yaml

@@ -1,5 +1,3 @@
-# Cloud Regions and Tiers
-
 Usage tiers define the sizing of a cluster and provide tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region and the cluster type (BYOC, Dedicated). See [BYOC tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/byoc-tiers/) and [Dedicated tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/dedicated-tiers/) for further details.
 
 <h3>GCP</h3><table><tr><th>Region</th><th>Zones</th><th>Throughput Tiers</th></tr><tr><td>europe-west9</td><td>europe-west9-a,europe-west9-b,europe-west9-c</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>europe-southwest1</td><td>europe-southwest1-a,europe-southwest1-b,europe-southwest1-c</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>southamerica-west1</td><td>southamerica-west1-b</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>asia-east1</td><td>asia-east1-a,asia-east1-b,asia-east1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>asia-northeast1</td><td>asia-northeast1-a,asia-northeast1-b,asia-northeast1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>asia-south1</td><td>asia-south1-a,asia-south1-b,asia-south1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>asia-southeast1</td><td>asia-southeast1-a,asia-southeast1-b,asia-southeast1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>australia-southeast1</td><td>australia-southeast1-a,australia-southeast1-b,australia-southeast1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>europe-west1</td><td>europe-west1-b,europe-west1-c,europe-west1-d</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>europe-west2</td><td>europe-west2-a,europe-west2-b,europe-west2-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>europe-west3</td><td>europe-west3-a,europe-west3-b,europe-west3-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: Dedicated, BYOC<br>tier-7-gcp-v2-x86: Dedicated, BYOC<br>tier-8-gcp-v2-x86: Dedicated, BYOC<br>tier-9-gcp-v2-x86: Dedicated, BYOC<br></td></tr><tr><td>europe-west4</td><td>europe-west4-a,europe-west4-b,europe-west4-c</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>northamerica-northeast1</td><td>northamerica-northeast1-a,northamerica-northeast1-b,northamerica-northeast1-c</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>southamerica-east1</td><td>southamerica-east1-b,southamerica-east1-c,southamerica-east1-a</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>us-central1</td><td>us-central1-a,us-central1-b,us-central1-c,us-central1-f</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>us-east1</td><td>us-east1-b,us-east1-c,us-east1-d</td><td>tier-1-gcp-v2-x86: Dedicated, BYOC<br>tier-2-gcp-v2-x86: Dedicated, BYOC<br>tier-3-gcp-v2-x86: Dedicated, BYOC<br>tier-4-gcp-v2-x86: Dedicated, BYOC<br>tier-5-gcp-v2-x86: Dedicated, BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>us-east4</td><td>us-east4-a,us-east4-b,us-east4-c</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr><tr><td>us-west1</td><td>us-west1-a,us-west1-b,us-west1-c</td><td>tier-1-gcp-v2-x86: BYOC<br>tier-2-gcp-v2-x86: BYOC<br>tier-3-gcp-v2-x86: BYOC<br>tier-4-gcp-v2-x86: BYOC<br>tier-5-gcp-v2-x86: BYOC<br>tier-6-gcp-v2-x86: BYOC<br>tier-7-gcp-v2-x86: BYOC<br>tier-8-gcp-v2-x86: BYOC<br>tier-9-gcp-v2-x86: BYOC<br></td></tr></table><h3>AWS</h3>

cloud-controlplane/x-topics/cloud-regions.md

@@ -1,5 +1,3 @@
-# Control Plane API Error and Status Codes
-
 The Redpanda Cloud API uses HTTP codes to indicate the status of a request. The response payload also includes [additional error codes and descriptions](#error-codes-and-details) that provide more detail about why an operation failed.
 
 Example request:

cloud-controlplane/x-topics/error-and-status-codes.md

@@ -1,5 +1,3 @@
-# Long-running Operations in Redpanda Cloud
-
 Some Cloud API endpoints do not directly return the resource itself, but instead return an operation. These operations may be long-running, meaning they may not complete immediately and can take several seconds or minutes to finish. Examples include creating or deleting clusters and networks, and updating cluster properties. Long-running operations are asynchronous and return a response indicating that the request has been accepted and is being processed.
 
 When you initiate a long-running operation, the API responds with a status code such as `202 Accepted` and includes an operation ID. The following is an example response of Create Cluster:

cloud-controlplane/x-topics/long-running-operations.md

@@ -1,6 +1,4 @@
-# Redpanda Cloud Control Plane API Quickstart
-
-The following steps describe how to authenticate with the Control API and create a new Redpanda cluster. For more information on the Control Plane API, see the Redpanda Cloud API Overview.
+The following steps describe how to authenticate with the Control API and create a new Redpanda cluster. For more information on the Control Plane API, see the Cloud API Overview.
 
 > **Note:** Redpanda Cloud uses a control plane and data plane architecture. 
 To see the available endpoints for managing resources within your clusters, such as topics, users, access control lists (ACLs), and connectors, see the Data Plane API Reference.
@@ -12,28 +10,32 @@ To use the Control Plane API:
 1. You must be a customer with an existing organization in Redpanda Cloud.
 2. You can only use one organization for authentication.
 
+**BYOC only**: To create a BYOC cluster, [install or update `rpk`](https://docs.redpanda.com/redpanda-cloud/manage/rpk/rpk-install).
+
 ### Authenticate to the API from API Explorer
 
-You can issue requests against the Control Plane API from your browser when viewing the API Explorer:
+To make API requests in your browser, you must obtain an access token. You can do so by clicking **Get token** on the API endpoint you want to call.
 
-1. In the Redpanda Cloud UI, create a [service account (client)](https://cloud.redpanda.com/organization-iam?tab=service-accounts). Save the client ID and secret.
-1. Go to the "Get access token" endpoint and click **Run in API Explorer**.
-1. In the request body:
-  1. For `grant_type`, select `client_credentials`.
-  1. Enter the `client_id` and `client_secret` values you generated using the service account.
-  1. For `audience`, select `cloudv2-production.redpanda.cloud`. 
-1. Click **Send Request** on the code example to the right.
-The Response block should populate with an `access_token` value. Copy the string value without the quotes. To make your next request to a different endpoint in the API Explorer, add the access token in the Authentication field.
-> **Warning:** API requests from this page are executed against your actual environment and data, not a sandbox.
+If you successfully retrieve an access token, it is valid for one hour. You can use the same token in requests to both Control Plane and Data Plane API endpoints, for as long as the token is valid.
 
 ## Create a new cluster
 
+> **Warning:** API requests from the API Explorer are executed against your actual environment and data, not a sandbox.
+
 ### BYOC or Dedicated
 
-1. Create a resource group by making a Create Resource Group request. The response returns a resource group ID. Pass this ID later when you call the Create Cluster endpoint.
-1. Create a network by making a Create Network request. Note that this endpoint returns a long-running operation. The response returns a network ID in `resource_id`. Pass this ID when you call the Create Cluster endpoint.  
-1. When the Create Network operation is complete, create a cluster by making a Create Cluster request. Note that this endpoint returns a long-running operation.
-1. For BYOC, run `rpk cloud byoc` in the shell, passing the `metadata.cluster_id` from the Create Cluster response as a flag:
+1. In the page header, click **API Explorer**.
+1. On the **Choose an operation** dropdown, select **Create resource group**.
+1. Click **Get token**. You may be prompted to log in to the Redpanda Cloud UI. After you log in, the browser automatically redirects you back to the Create resource group endpoint in the API Explorer.
+1. Prepare your Create resource group request.
+  1. Under **Body**, click **+ Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
+  1. Click **Send request**. If successful, the response returns a resource group ID. Pass this ID when you make a Create network request. 
+1. On the dropdown, select **Create network**.
+1. Prepare your Create network request.
+  1. Include the ID of the resource group you created in the previous step. 
+  1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a network ID in `metadata.network_id`. Pass this ID when you call the Create Cluster endpoint.To check the operation state, make a **Get operation** request with the `operation.id`.  
+1. When the Create network operation is complete, make a Create cluster request. Use the resource group and network IDs you just created. Note that this endpoint also returns a long-running operation.
+1. For BYOC, run `rpk cloud byoc` in the shell, passing the `metadata.cluster_id` from the Create cluster response as a flag:
 
    **AWS:**
    ```bash
@@ -50,7 +52,30 @@ The Response block should populate with an `access_token` value. Copy the string
 
 ### Serverless
 
-1. Make a Get Resource Group request to retrieve the default resource group ID. Pass this ID later when you call the Create Serverless Cluster endpoint.
-1. Make a Get Serverless Regions request to see available regions.
-1. Create a cluster by making a Create Serverless Cluster request, passing in the default resource group ID and desired cloud region in the request.
+1. In the page header, click **API Explorer**.
+1. On the **Choose an operation** dropdown, select **Create resource group**.
+1. Click **Get token**. You may be prompted to log in to the Redpanda Cloud UI. After you log in, the browser automatically redirects you back to the Create resource group endpoint in the API Explorer.
+1. Prepare your Create resource group request.
+  1. Under **Body**, click **+ Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
+  1. Click **Send request**. If successful, the response returns a resource group ID. Pass this ID later when you make a Create Serverless cluster request. 
+1. On the dropdown, select **Create Serverless cluster**. 
+1. Prepare your Create Serverless cluster request.
+  1. Make a Get Serverless Regions request to see available regions.
+  1. In the request body, use the resource group ID and desired cloud region.
+  1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a Serverless cluster ID in `metadata.cluster_id`. To check the operation state, make a **Get operation** request with the `operation.id`.
+
+## Next steps: try the Data Plane APIs
+
+1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer.
+1. Save the value of `dataplane_api.url` from the response body.
+1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**.
+1. Select an operation, for example **Create topic** or **List users**. 
+1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster.
+
+See also: [Data Plane API Quickstart](https://docs.redpanda.com/api/doc/cloud-dataplane/topic/topic-quickstart)
+
+## Suggested reading
 
+- Learn about Redpanda Cloud [network security and connectivity](https://docs.redpanda.com/redpanda-cloud/networking/) for BYOC and Dedicated clusters.
+- Manage [authentication and authorization](https://docs.redpanda.com/redpanda-cloud/security/authorization/) in Redpanda Cloud.
+- [Create a Kafka client or generate a sample application](https://docs.redpanda.com/redpanda-cloud/get-started/cluster-types/serverless/#connect-with-your-cluster) to interact with your Serverless cluster.