Skip to content

Serverless API docs improvements #657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
kbatuigas wants to merge 9 commits into from
Closed

Serverless API docs improvements #657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ea5a4ee
Edits per PM input
kbatuigas Jul 31, 2024
96db235
Add auth header to curl commands
kbatuigas Jul 31, 2024
b52a207
Merge branch 'main' of github.com:redpanda-data/docs
kbatuigas Aug 1, 2024
3c866bf
API reference links are live
kbatuigas Aug 1, 2024
0592fcc
Apply suggestions from code review
kbatuigas Aug 1, 2024
c72ea1f
Add double quotes and fix incorrect request body example for code blocks
kbatuigas Aug 1, 2024
2534cce
Merge remote-tracking branch 'origin/serverless-api-doc-impvt' into s…
kbatuigas Aug 1, 2024
af4f8d6
Add double quote tip for shell variables in auth header
kbatuigas Aug 1, 2024
f7b5c39
Move TIP to earlier in the serverless version of control plane doc
kbatuigas Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ You only need to authenticate once to the Cloud API. That is, after you obtain a
== Request an access token

Users with administrative privileges in a Redpanda Cloud organization can create a service account.

NOTE: Service accounts have administrative privileges by default. Cloud user roles are not applied for the API.

// UI change not applied
Expand All @@ -31,4 +32,6 @@ You must pass the access token in the authorization header of each API request:

```bash
curl -H "Authorization: Bearer $YOUR_TOKEN"
```
```

TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value.
31 changes: 27 additions & 4 deletions modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The following steps describe how to authenticate with the Cloud API and create a
BYOC or Dedicated::
+
--
. xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Authenticate to the API].
. 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:ROOT:deploy:deployment-option/cloud/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.
Expand All @@ -35,8 +35,31 @@ rpk cloud byoc aws apply --redpanda-id=<metadata.cluster_id>
Serverless::
+
--
. xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Authenticate to the API].
. Create a cluster by making a `POST /v1beta2/serverless/clusters` request.
. 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:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[authenticate to the API].
. Make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/resource-groups[`GET /v1beta2/resource-groups`] request to retrieve the default resource group ID.
+
[,bash]
----
curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1beta2/resource-groups
----
. Make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/regions[`GET /v1beta2/serverless/regions`] request to see available regions.
+
[,bash]
----
curl -H "Authorization: Bearer <token>" 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS'
----
. Create a cluster by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[`POST /v1beta2/serverless/clusters`] request.
+
[,bash]
----
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer <token>" \
-d '{
"name": <serverless-cluster-name>,
"resource_group_id": <resource-group-id>,
"serverless_region": "pro-us-east-1"
}' -X POST https://api.redpanda.com/v1beta2/serverless/clusters
----
--
======

Expand Down Expand Up @@ -65,7 +88,7 @@ For requests to the Control Plane API endpoints:

For requests to the Data Plane API endpoints:

. Make a Get Cluster request for your target cluster.
. Make a Get Cluster (BYOC, Dedicated) or Get Serverless Cluster (Serverless) request for your target cluster.
. The Get Cluster response contains the Data Plane API URL. Copy the value of `dataplane_api.url` from the response body.
. Click *API Servers* in the sidebar and select “\{dataplane_api_url} - Data Plane API”.
. Paste the URL into the `dataplane_api_url` input field.
Expand Down
31 changes: 25 additions & 6 deletions modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,20 @@ The xref:deploy:deployment-option/cloud/api/cloud-api-overview.adoc#cloud-api-ar

== Get Data Plane API URL

[tabs]
======
BYOC or Dedicated::
+
--
To retrieve the Data Plane API URL of a cluster, make a request to xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`].
--

Serverless::
+
--
To retrieve the Data Plane API URL of a cluster, make a request to xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/clusters/-id-[`GET /v1beta2/serverless/clusters/\{id}`].
--
======

The response includes a `dataplane_api.url` value:

Expand All @@ -35,12 +48,14 @@ To create a new user in your Redpanda cluster, make a POST request to the xref:a
[,bash]
----
curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/users" \
-H "accept: application/json"\

-H "Authorization: Bearer <token>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"mechanism":"SASL_MECHANISM_SCRAM_SHA_256","name":"payment-service","password":"secure-password"}'
----

TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value.

The success response returns the newly-created username and SASL mechanism:

[.no-copy]
Expand All @@ -60,7 +75,8 @@ To create a new ACL in your Redpanda cluster, make a xref:api:ROOT:cloud-api.ado
[,bash]
----
curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/acls" \
-H "accept: application/json"\
-H "Authorization: Bearer <token>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"host":"*","operation":"OPERATION_ALL","permission_type":"PERMISSION_TYPE_ALLOW","principal":"User:payment-service","resource_name":"*","resource_pattern_type":"RESOURCE_PATTERN_TYPE_LITERAL","resource_type":"RESOURCE_TYPE_TOPIC"}'
----
Expand All @@ -79,7 +95,8 @@ To create a new Redpanda topic without specifying any further parameters, such a
[,bash]
----
curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/topics" \
-H "accept: application/json"\
-H "Authorization: Bearer <token>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"name":"my-simple-test-topic"}'
----
Expand All @@ -93,8 +110,9 @@ To create a managed connector, make a POST request to xref:api:ROOT:cloud-api.ad
[,bash]
----
curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/connect/clusters/redpanda/connectors" \
-H "accept: application/json"\
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{"config":{"connector.class":"com.redpanda.kafka.connect.s3.S3SinkConnector","topics":"test-topic","aws.secret.access.key":"secret-key","aws.s3.bucket.name":"bucket-name","aws.access.key.id":"access-key","aws.s3.bucket.check":"false","region":"us-east-1"},"name":"my-sample-connector"}'
----

Expand Down Expand Up @@ -128,6 +146,7 @@ To restart a connector, make a POST request to the xref:api:ROOT:cloud-api.adoc#
[,bash]
----
curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/connect/clusters/redpanda/connectors/my-connector/restart" \
-H "Authorization: Bearer <token>" \
-H "accept: application/json"\
-H "content-type: application/json" \
-d '{"include_tasks":false,"only_failed":false}'
Expand Down
110 changes: 75 additions & 35 deletions modules/deploy/partials/cloud/controlplane-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,13 @@ endif::[]
* pass:a,m[xref:{tag-operations}[OperationService\]]
* pass:a,m[xref:{tag-resource-groups}[ResourceGroupService\]]
ifdef::env-serverless[]
* ServerlessClusterService
* ServerlessRegionService
// TODO: Update xref when prod spec contains serverless endpoints
// * pass:a,m[xref:{tag-serverless-clusters}[ServerlessClusterService\]]
// * pass:a,m[xref:{tag-serverless-regions}[ServerlessRegionService\]]
* pass:a,m[xref:{tag-serverless-clusters}[ServerlessClusterService\]]
* pass:a,m[xref:{tag-serverless-regions}[ServerlessRegionService\]]
endif::[]


// For serverless, show this section at the end of the doc
ifndef::env-serverless[]
[[lro]]
== Long-running operations

Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of xref:api:ROOT:cloud-api.adoc#post-/v1beta2/clusters[Create Cluster] (`POST /clusters`):
Expand Down Expand Up @@ -58,12 +57,12 @@ The response object represents the long-running operation of creating a cluster.
To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter:

```bash
curl https://api.redpanda.com/v1beta2/operations/<operation-id>
curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1beta2/operations/<operation-id>
```

The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`.
TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value.

ifndef::env-serverless[]
The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`.

== Cluster tiers

Expand All @@ -83,7 +82,7 @@ Create a resource group by making a POST request to the xref:api:ROOT:cloud-api.
[,bash]
----
curl -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-H "Authorization: Bearer <token>" \
-d '{
"name": "<resource-group-name>"
}' -X POST https://api.redpanda.com/v1beta2/resource-groups
Expand All @@ -107,10 +106,10 @@ curl -d \
"name": "<network-name>",
"resource_group_id": "<resource-group-id>",
"region": "us-west1"
}' -X POST https://api.redpanda.com/v1beta2/networks
}' -H "Authorization: Bearer <token>" -X POST https://api.redpanda.com/v1beta2/networks
----

This endpoint returns a <<long_running_operations,long-running operation>>.
This endpoint returns a <<lro,long-running operation>>.

=== Create a new cluster

Expand All @@ -133,10 +132,10 @@ curl -d \
"us-west1-b",
"us-west1-c"
]
}' -X POST https://api.redpanda.com/v1beta2/clusters
}' -H "Authorization: Bearer <token>" -X POST https://api.redpanda.com/v1beta2/clusters
----

The Create Cluster endpoint returns a <<long_running_operations,long-running operation>>. When the operation is completed, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`], passing the cluster ID as a parameter.
The Create Cluster endpoint returns a <<lro,long-running operation>>. When the operation completes, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`], and passing the cluster ID as a parameter.

ifdef::env-byoc[]
==== Additional steps to create a BYOC cluster
Expand Down Expand Up @@ -169,14 +168,22 @@ To create a new serverless cluster, you can use the default resource group, or c

=== Create a resource group

NOTE: This step is optional. Serverless includes a default resource group. Skip this step to use the default.
[NOTE]
====
This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/resource-groups[`/v1beta2/resource-groups`] endpoint:

```bash
curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1beta2/resource-groups
```

====

Create a resource group by making a POST request to the xref:api:ROOT:cloud-api.adoc#post-/v1beta2/resource-groups[`/v1beta2/resource-groups`] endpoint. Pass a name for your resource group in the request body.

[,bash]
----
curl -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-H "Authorization: Bearer <token>" \
-d '{
"name": "<serverless-resource-group-name>"
}' -X POST https://api.redpanda.com/v1beta2/resource-groups
Expand All @@ -186,14 +193,15 @@ A resource group ID is returned. Pass this ID later when you call the Create Ser

=== Choose a region

// TODO: Update xref when prod spec contains serverless endpoints
To see the available regions for Redpanda Serverless, make a GET request to the `/v1beta2/serverless/regions` endpoint. You can specify a cloud provider in your request. Serverless currently only supports AWS.
To see the available regions for Redpanda Serverless, make a GET request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/regions[`/v1beta2/serverless/regions`] endpoint. You can specify a cloud provider in your request. Serverless currently only supports AWS.

[,bash]
----
curl -H 'Authorization: Bearer <token>' https://api.redpanda.com/v1beta2/serverless/regions/
curl -H "Authorization: Bearer <token>" 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS'
----

TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value.

[,json,role=no-copy]
----
{
Expand All @@ -205,7 +213,8 @@ curl -H 'Authorization: Bearer <token>' https://api.redpanda.com/v1beta2/serverl
"id": "Europe/Berlin",
"version": ""
},
"cloud_provider": "CLOUD_PROVIDER_AWS"
"cloud_provider": "CLOUD_PROVIDER_AWS",
"available": true
},
{
"name": "pro-us-east-1",
Expand All @@ -214,7 +223,8 @@ curl -H 'Authorization: Bearer <token>' https://api.redpanda.com/v1beta2/serverl
"id": "America/New_York",
"version": ""
},
"cloud_provider": "CLOUD_PROVIDER_AWS"
"cloud_provider": "CLOUD_PROVIDER_AWS",
"available": true
}
],
"next_page_token": ""
Expand All @@ -224,34 +234,31 @@ curl -H 'Authorization: Bearer <token>' https://api.redpanda.com/v1beta2/serverl

=== Create a new serverless cluster

// TODO: Update xref when prod spec contains serverless endpoints
Create a Serverless cluster by making a request to `POST /v1beta2/serverless/clusters` with the resource group ID and serverless region name in the request body.
Create a Serverless cluster by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[`POST /v1beta2/serverless/clusters`] with the resource group ID and serverless region name in the request body.

[,bash]
----
curl -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-H "Authorization: Bearer <token>" \
-d '{
"serverless_cluster": {
"name": <serverless-cluster-name>,
"resource_group_id": <resource-group-id>,
"serverless_region": "pro-us-east-1"
}
"name": <serverless-cluster-name>,
"resource_group_id": <resource-group-id>,
"serverless_region": "pro-us-east-1"
}' -X POST https://api.redpanda.com/v1beta2/serverless/clusters
----

The Create Serverless Cluster endpoint returns a <<long_running_operations,long-running operation>>. When the operation is completed, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, passing the cluster ID as a parameter.
The Create Serverless Cluster endpoint returns a <<lro-serverless,long-running operation>>. When the operation completes, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/clusters/-id-[`GET /v1beta2/serverless/clusters/\{id}`], and passing the cluster ID as a parameter.

endif::[]

== Delete a cluster

ifndef::env-serverless[]

To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<long_running_operations,long-running operation>>.
To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro,long-running operation>>.

```bash
curl -X DELETE https://api.redpanda.com/v1beta2/clusters/<cluster_id>
curl -H "Authorization: Bearer <token>" -X DELETE https://api.redpanda.com/v1beta2/clusters/<cluster_id>
```

ifdef::env-byoc[]
Expand Down Expand Up @@ -286,15 +293,48 @@ endif::[]

ifdef::env-serverless[]

// TODO: Update xref when prod spec contains serverless endpoints
To delete a cluster, make a request to the `DELETE /v1beta2/serverless/clusters/\{id}` endpoint, passing the cluster ID as a parameter. This is a <<long_running_operations,long-running operation>>.
To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/serverless/clusters/-id-[`DELETE /v1beta2/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>.

```bash
curl -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/<cluster-id>
curl -H "Authorization: Bearer <token>" -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/<cluster-id>
```

Optional: When the cluster is deleted, the delete operation’s state changes to `STATE_COMPLETED`. At this point, you may make a DELETE request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/resource-groups/-id-[`/v1beta2/resource-groups/\{id}`] endpoint to delete the resource group.

[[lro-serverless]]
== Long-running operations

Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[Create Serverless Cluster] (`POST /serverless/clusters`):

[,bash,role=no-copy]
----
{
"operation": {
"id": "cqaramrndjr40k3qei50",
"metadata": null,
"state": "STATE_IN_PROGRESS",
"started_at": {
"seconds": "1721087323",
"nanos": 888601218
},
"finished_at": null,
"type": "TYPE_CREATE_SERVERLESS_CLUSTER"
}
}
----

The response object represents the long-running operation of creating a cluster. Cluster creation is an example of an operation that can take a longer period of time to complete.

=== Check operation state

To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter:

```bash
curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1beta2/operations/<operation-id>
```

The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`.

endif::[]

== Next steps
Expand Down