Skip to content

Commit 685483c

Browse files
kbatuigaskbatuigas
committed
Add refactored usage docs for Cloud API
1 parent 5f40741 commit 685483c

File tree

8 files changed

+229
-6
lines changed

8 files changed

+229
-6
lines changed

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Long-running Operations in Redpanda Cloud
2+
3+
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.
4+
5+
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:
6+
7+
```json
8+
{
9+
"operation": {
10+
"id": "cqfc6vdmvio001r4vu4",
11+
"metadata": {
12+
"@type": "type.googleapis.com/redpanda.api.controlplane.v1.CreateClusterMetadata",
13+
"cluster_id": "cqg168balf4e4pm8ptu"
14+
},
15+
"state": "STATE_IN_PROGRESS",
16+
"started_at": "2024-07-23T20:31:29.948Z",
17+
"type": "TYPE_CREATE_CLUSTER",
18+
"resource_id": "cqg168balf4e4pm8ptu"
19+
}
20+
}
21+
```
22+
23+
You can use the operation ID to poll the status of the operation or check for completion.
24+
25+
## Work with long-running operations
26+
27+
1. Send the request to start a long-running operation (for example, create a network).
28+
2. Receive a response with an operation ID.
29+
3. Poll the Get Operation endpoint using the provided ID.
30+
4. Check for completion. When the operation is complete, the status will indicate success or failure, and any resulting resources will be available for next steps in your workflow (for example, using a newly-created network to create a cluster).
31+
32+
## Best practices
33+
34+
- Always check the operation status before assuming completion.
35+
- Handle possible statuses `STATE_IN_PROGRESS`, `STATE_COMPLETED`, and `STATE_FAILED`.
36+
- Review API documentation for specific endpoints that support long-running operations and their status-checking mechanisms.
37+
38+
For more details, refer to the Get Operation endpoint reference or the relevant endpoint reference.

‎cloud-controlplane/overlays/add-x-topics.yaml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@ actions:
99
description: Add x-topics to the root of the document
1010
update:
1111
x-topics:
12-
# - title: Quickstart
13-
# content: quickstart.md
12+
- title: Quickstart
13+
content:
14+
$ref: ../x-topics/controlplane-api-quickstart.md
15+
- title: Cloud API Overview
16+
content:
17+
$ref: ../../shared/x-topics/cloud-api-overview.md
1418
- title: Authentication
1519
content:
1620
$ref: ../../shared/x-topics/about-authentication.md

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Cloud Control Plane API Error and Status Codes
1+
# Control Plane API Error and Status Codes
22

33
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.
44

‎cloud-controlplane/x-topics/controlplane-api-quickstart.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Redpanda Cloud Control Plane API Quickstart
2+
3+
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.
4+
5+
> **Note:** Redpanda Cloud uses a control plane and data plane architecture.
6+
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.
7+
8+
## Requirements
9+
10+
To use the Control Plane API:
11+
12+
1. You must be a customer with an existing organization in Redpanda Cloud.
13+
2. You can only use one organization for authentication.
14+
15+
### Authenticate to the API from API Explorer
16+
17+
You can issue requests against the Control Plane API from your browser when viewing the API Explorer:
18+
19+
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.
20+
1. Go to the "Get access token" endpoint and click **Run in API Explorer**.
21+
1. In the request body:
22+
1. For `grant_type`, select `client_credentials`.
23+
1. Enter the `client_id` and `client_secret` values you generated using the service account.
24+
1. For `audience`, select `cloudv2-production.redpanda.cloud`.
25+
1. Click **Send Request** on the code example to the right.
26+
27+
The Response block should populate with an `access_token` value. Copy the string value without the quotes. To you make your next request on a different endpoint in the API Explorer, add the access token in the Authentication field.
28+
29+
> **Warning:** API requests from this page are executed against your actual environment and data, not a sandbox.
30+
31+
## Create a new cluster
32+
33+
### BYOC or Dedicated
34+
35+
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.
36+
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.
37+
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.
38+
1. For BYOC, run `rpk cloud byoc` in the shell, passing the `metadata.cluster_id` from the Create Cluster response as a flag:
39+
40+
**AWS:**
41+
```bash
42+
rpk cloud byoc aws apply --redpanda-id=<metadata.cluster_id>
43+
```
44+
**Azure:**
45+
```bash
46+
rpk cloud byoc azure apply --redpanda-id=<metadata.cluster_id> --subscription-id=<redpanda-cluster-azure-subscription-id>
47+
```
48+
**GCP:**
49+
```bash
50+
rpk cloud byoc gcp apply --redpanda-id=<metadata.cluster_id> --project-id=<gcp-project-id>
51+
```
52+
53+
### Serverless
54+
55+
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.
56+
1. Make a Get Serverless Regions request to see available regions.
57+
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.
58+

‎cloud-dataplane/overlays/add-x-topics.yaml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@ actions:
99
description: Add x-topics to the root of the document
1010
update:
1111
x-topics:
12-
# - title: Quickstart
13-
# content: quickstart.md
12+
- title: Quickstart
13+
content:
14+
$ref: ../x-topics/dataplane-api-quickstart.md
15+
- title: Cloud API Overview
16+
content:
17+
$ref: ../../shared/x-topics/cloud-api-overview.md
1418
- title: Authentication
1519
content:
1620
$ref: ../../shared/x-topics/about-authentication.md

‎cloud-dataplane/x-topics/dataplane-api-error-and-status-codes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Cloud Data Plane API Error and Status Codes
1+
# Data Plane API Error and Status Codes
22

33
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.
44

‎cloud-dataplane/x-topics/dataplane-api-quickstart.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Redpanda Cloud Data Plane API Quickstart
2+
3+
The following steps describe how to authenticate with the Data Plane API. For more information on the Data Plane API, see the Redpanda Cloud API Overview.
4+
5+
> **Note:** Redpanda Cloud uses a control plane and data plane architecture. To see the available endpoints for managing your clusters, networks, and resource groups, see the Control Plane API Reference.
6+
7+
## Requirements
8+
9+
To use the Data Plane API:
10+
11+
1. You must be a customer with an existing organization in Redpanda Cloud.
12+
2. You can only use one organization for authentication.
13+
3. You must have a running cluster in Redpanda Cloud.
14+
15+
### Authenticate to the API from API Explorer
16+
17+
You can issue requests against the Data Plane API from your browser when viewing the API Explorer:
18+
19+
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.
20+
1. Go to the "Get access token" endpoint and click **Run in API Explorer**.
21+
1. In the request body:
22+
1. For `grant_type`, select `client_credentials`.
23+
1. Enter the `client_id` and `client_secret` values you generated using the service account.
24+
1. For `audience`, select `cloudv2-production.redpanda.cloud`.
25+
1. Click **Send Request** on the code example to the right.
26+
27+
The Response block should populate with an `access_token` value. Copy the string value without the quotes. To you make your next request on a different endpoint in the API Explorer, add the access token in the Authentication field.
28+
29+
> **Warning:** API requests from this page are executed against your actual environment and data, not a sandbox.
30+
31+
## Create a topic
32+
33+
1. If you don't already have the data plane API URL for your target cluster, make a Get Cluster (BYOC, Dedicated) or Get Serverless Cluster (Serverless) request against the Control Plane API. The response contains the Data Plane API URL. Copy the value of `dataplane_api.url` from the response body.
34+
1. Go to **API Servers** in the sidebar and select “\{dataplane_api_url} - Data Plane API”. Paste the URL into the `dataplane_api_url` field.
35+
1. To create a new Redpanda topic, make a Create Topic request.
36+
37+
38+

‎shared/x-topics/cloud-api-overview.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Redpanda Cloud API Overview
2+
3+
The Redpanda Cloud API is a collection of REST APIs that allow you to interact with different parts of Redpanda Cloud. You can call the API endpoints directly, or use tools like Terraform or Python scripts to automate cluster management and manage Redpanda Cloud resources.
4+
5+
## Requirements
6+
7+
To use the Cloud API:
8+
9+
- You must have a Redpanda Cloud account.
10+
- You can only use one organization for authentication. See Authentication for steps to authenticate API requests.
11+
- Serverless: To try the Cloud API with Serverless, [sign up for a free Standard trial](https://redpanda.com/cloud/serverless).
12+
13+
## Cloud API architecture
14+
15+
Redpanda Cloud uses a control plane and data plane architecture. The **control plane** is where most cluster management, operations, and maintenance takes place. The control plane enforces rules in the data plane. The **data plane** is where your cluster lives. The term _data plane_ is used interchangeably with _cluster_. For BYOC customers, the data plane is in your VPC. To learn more about the Redpanda Cloud platform, see the [Cloud Overview](https://docs.redpanda.com/docs/cloud/cloud-overview/).
16+
17+
The **Control Plane API** allows you to interact with the control plane. You use the Control Plane API to manage cloud resources for your organization, like clusters, resource groups, and networks. The Control Plane API does not interact directly with Redpanda clusters, although some of the actions performed through the API can eventually make their way to a cluster. See [Use the Control Plane API](https://docs.redpanda.com/docs/manage/api/controlplane/) for steps to create and delete clusters.
18+
19+
The **Data Plane APIs** are a collection of APIs through which you can perform actions directly against a Redpanda cluster. These APIs expose more high-level operations on the data plane by acting as a wrapper around the other APIs supported by Redpanda (Kafka API, Admin API, or Schema Registry API). See [Use the Data Plane APIs](https://docs.redpanda.com/docs/manage/api/cloud-dataplane-api/) for steps to create an access-control list (ACL), topic, or connector.
20+
21+
See also:
22+
23+
- [Redpanda API and SDK Reference documentation](https://docs.redpanda.com/reference/api-reference/)
24+
25+
## Base URLs
26+
27+
The Control Plane and Data Plane APIs are independent of each other. The Cloud API URL is distinct from the Data Plane API URLs.
28+
29+
### Control Plane API URL
30+
31+
The Control Plane API has a base URL that is the same for any organization:
32+
33+
```
34+
https://api.redpanda.com
35+
```
36+
37+
When making requests to the Control Plane API endpoints, the request URL is the base URL, plus the API version, plus the resource path. For example:
38+
39+
```bash
40+
https://api.redpanda.com/v1/clusters
41+
```
42+
43+
The current Control Plane API version is **v1**.
44+
45+
> **Important:** The Control Plane API versions v1beta1 and v1beta2 are deprecated. v1beta1 and v1beta2 are still available, but they will be removed in a future release and are not recommended for use.
46+
>
47+
> The deprecation timeline is:
48+
>
49+
> - Announcement date: May 27, 2025
50+
> - End-of-support date: November 28, 2025
51+
> - Retirement date: May 28, 2026
52+
>
53+
> See Deprecation Policy for more information.
54+
55+
### Data Plane APIs URL
56+
57+
The Data Plane API base URL is unique to the individual target cluster. It is different for each cluster. When making requests to the Data Plane API endpoints, the request URL is the base URL, plus the API version, plus the resource path. For example:
58+
59+
```bash
60+
https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1/users
61+
```
62+
63+
The current Data Plane API version is **v1**.
64+
65+
> **Important:** The Data Plane API versions v1alpha1 and v1alpha2 are deprecated. v1alpha1 and v1alpha2 are still available, but they will be removed in a future release and are not recommended for use.
66+
>
67+
> The deprecation timeline is:
68+
>
69+
> - Announcement date: May 27, 2025
70+
> - End-of-support date: November 28, 2025
71+
> - Retirement date: May 28, 2026
72+
>
73+
> See Deprecation Policy for more information.
74+
75+
## Pagination
76+
77+
When an endpoint returns a list containing more items than can be returned in a single response, the response object includes a `next_page_token`. You can pass the token value as a parameter in the next request. When the full list has been returned, `next_page_token` is an empty string.
78+
79+
## Versioning and deprecation
80+
81+
The Cloud API Deprecation Policy outlines the process for phasing out an API version or specific features within an API. See Deprecation Policy for details.

0 commit comments

Comments
 (0)