Schema Registry Clusters API Quick Start for Confluent Cloud¶
This page provides links to the Confluent Cloud Schema Registry API reference, a concept introduction to the model, an explanation of how to test the API calls, and detailed usage examples for all available actions.
Overview¶
Stream Governance is available on several Confluent Cloud hosted regions into which you can provision per-environment Schema Registry Clusters with Essentials or Advanced packages.
In addition to managing these Schema Registry Clusters with the Confluent Cloud Console and Confluent CLI , you can use a collection of REST APIs to provision and enable Stream Governance packages for your Confluent Cloud environments.
Most actions described below relate to managing Schema Registry Clusters (list, create, read, update, and so on). Two read-only actions are available to get the Schema Registry region information you need to provide in order to create Schema Registry Clusters.
This document is meant to supplement the API reference documentation for Schema Registry regions and clusters, which is linked below.
You can perform the following operations on Schema Registry Regions with this API:
You can perform the following operations on Schema Registry Clusters with this API:
Base URL¶
The base URL for Schema Registry region and cluster management calls is:
https://api.confluent.cloud/
Object model¶
All Confluent objects share a set of common properties:
api_version
: Indicates the API version for the object. The version for these APIs issrcm/v2
.kind
: Indicates what kind of object it is.id
: An identifier for the object.
Authentication¶
Each request to the server must include an Authorization: Basic {key}
header that contains
a Confluent Cloud API key. For more details on creating or accessing your Confluent Cloud API keys, see Cloud API keys.
API requests without a correct authentication header will fail. An API key grants access to a
single Confluent cluster.
These keys grant API access to many resources, and should not be shared publicly to GitHub, in client-side code, and so forth.
HTTP Basic authorization requires the key to be colon-separated and base64-encoded.
For example, if your API Key is abcp7DEFGH123456789
and the corresponding Secret
is XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO
, generate a base64-encoded header with the following command on
MacOS or Linux:
echo -n "abcp7DEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64
The resulting authorization header will be:
Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=
Alternatively, if testing using Postman, specify Basic Auth and provide the API Key as the Username and the API Secret as the password and Postman will provide the encoding.
How to test using curl¶
The sections that follow describe how to format the API calls with GET and POST, as you would incorporate into your code. You can test the calls against Confluent Cloud from the command line using curl commands. You will need to log in to Confluent Cloud to do this. If you are new to the Confluent CLI, check out this handy commands reference.
For example:
Log on to Confluent Cloud with the Confluent CLI. (Provide username and password at prompts.)
confluent login --url https://confluent.cloud
Create a Confluent Cloud API key and secret:
confluent api-key create --resource cloud
Store the key and secret in variables:
export CCLOUD_KEY=<generated-API-key>
export CCLOUD_SECRET=<generated-API-secret>
Store the URL for Confluent Cloud in a variable:
export CCLOUD_URL=https://api.confluent.cloud/
Tip
The URL
https://confluent.cloud/api
should also work here.Now, use
curl
to run the API call to list Schema Registry regions:curl -u $CCLOUD_KEY:$CCLOUD_SECRET "$CCLOUD_URL/srcm/v2/regions"
Your output should be similar to that shown in the example response for List regions below.
Schema Registry regions¶
List regions¶
Request example¶
API reference link: List of Regions
The following example shows how to list all available regions.
GET /srcm/v2/regions
Your request can include the following query parameters:
Parameter | Required or Optional | Description |
---|---|---|
spec.cloud |
Optional | Filter results by cloud provider name, such as AWS |
spec.region.name |
Optional | Filter results by cloud provider region name, such as us-east-2 . |
spec.packages |
Optional | Filters for the specified package type. Valid values are ESSENTIALS or ADVANCED .
Note that this parameter (spec.packages ) can be repeated, and the API will return regions that
match any of the provided values. |
page_size |
Optional | Specifies an integer page size for the returned payload. Max value is 100. Default: 10. |
page_token |
Optional | Contains the opaque pagination token string. |
Example response¶
A successful call returns an HTTP 200 OK
and a JSON payload that shows all available regions
(if no filters are applied). The metadata for each region describes the Cloud, display name, the
packages in which it is available, and the region name. A subset of the output is shown below as an example.
{
"api_version": "srcm/v2",
"kind": "RegionList",
"metadata": {
"first": "https://api.confluent.cloud/srcm/v2/regions",
"last": "https://api.confluent.cloud/srcm/v2/regions?page_token=bcAOehAY8F16YD84Z1wT",
"prev": "https://api.confluent.cloud/srcm/v2/regions?page_token=YIXRY97wWYmwzrax4dld",
"next": "https://api.confluent.cloud/srcm/v2/regions?page_token=UvmDWOB1iwfAIBPj6EYb",
"total_size": 123
},
"data": [
{
"api_version": "srcm/v2",
"kind": "Region",
"id": "sgreg-1",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/regions/sgreg-1",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-1",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Ohio (us-east-2)",
"cloud": "AWS",
"region_name": "us-east-2",
"packages": [
"ESSENTIALS",
"ADVANCED"
]
}
}
]
}
...
Read a region¶
API reference link: Read a Region
Request example¶
The following example shows how to read a specific region by providing the region ID (obtained from the previous call to list regions).
GET /srcm/v2/regions/{id}
Your request must include the following query parameter:
Parameter | Required or Optional | Description |
---|---|---|
id |
Required | A string that is the unique identifier for the region. |
Example response¶
{
"api_version": "srcm/v2",
"kind": "Region",
"id": "sgreg-1",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/regions/sgreg-1",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-1",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Ohio (us-east-2)",
"cloud": "AWS",
"region_name": "us-east-2",
"packages": [
"ESSENTIALS",
"ADVANCED"
]
}
}
Schema Registry cluster management¶
List clusters¶
API reference link: List of Clusters
Request example¶
The following examples show how to retrieve a sorted, filtered, paginated list of all clusters.
GET /srcm/v2/clusters?environment={environment_id}
Your request can include the following query parameters:
Parameter | Required or Optional | Description |
---|---|---|
environment_id |
Required | Filter results by exact match for this environment ID. |
page_size |
Optional | Specifies an integer page size for the returned payload. Max value is 100. Default: 10. |
page_token |
Optional | Contains the opaque pagination token string. |
Example response¶
A successful call returns an HTTP 200 OK
and a JSON payload that contains a list of Schema Registry Clusters for the environment.
The response describes each cluster including the following information:
- The associated Stream governance package.
- The Schema Registry region for the cluster. See Cloud providers and region support for a full list of Schema Registry regions.
- The cluster status (PROVISIONED, PROVISIONING, FAILED).
- Information about the environment that contains the cluster.
{
"api_version": "srcm/v2",
"kind": "ClusterList",
"metadata": {
"first": "https://api.confluent.cloud/srcm/v2/clusters",
"last": "https://api.confluent.cloud/srcm/v2/clusters?page_token=bcAOehAY8F16YD84Z1wT",
"prev": "https://api.confluent.cloud/srcm/v2/clusters?page_token=YIXRY97wWYmwzrax4dld",
"next": "https://api.confluent.cloud/srcm/v2/clusters?page_token=UvmDWOB1iwfAIBPj6EYb",
"total_size": 123
},
"data": [
{
"api_version": "srcm/v2",
"kind": "Cluster",
"id": "lsrc-12345",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Stream Governance package",
"package": "ESSENTIALS",
"http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
"environment": {
"id": "env-00000",
"related": "https://api.confluent.cloud/v2/environments/env-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
},
"region": {
"id": "sgreg-00000",
"related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
}
},
"status": {
"phase": "PROVISIONED"
}
}
]
}
Create a cluster¶
API reference link: Create a Cluster
You can create a Schema Registry Cluster with a POST call to the cluster endpoint. Make sure you include the authorization header with your API key and API secret.
POST /srcm/v2/clusters
Request¶
When you make the request, include a JSON payload that contains a spec
object showing the desired state of the cluster.
Request specification¶
Parameter | Required or Optional | Description |
---|---|---|
package |
Required | Object that contains the Stream Governance package; either ESSENTIALS or ADVANCED . |
environment |
Required | Object that contains the environment identifier. |
region |
Required | Object that contains the Schema Registry region ID. |
Request example¶
{
"spec": {
"package": "ESSENTIALS",
"environment": {
"id": "env-00000"
},
"region": {
"id": "sgreg-00000"
}
}
}
Example response¶
Success returns an HTTP 202 ACCEPTED
with a JSON payload that describes the cluster. The cluster
description includes the following:
- The associated Stream Governance package (ESSENTIALS or ADVANCED).
- Information about the environment that contains the cluster.
- The Schema Registry region ID.
- The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
"api_version": "srcm/v2",
"kind": "Cluster",
"id": "lsrc-12345",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Stream Governance package",
"package": "ESSENTIALS",
"http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
"environment": {
"id": "env-00000",
"related": "https://api.confluent.cloud/v2/environments/env-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
},
"region": {
"id": "sgreg-00000",
"related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
}
},
"status": {
"phase": "PROVISIONED"
}
}
Read a cluster¶
API reference link: Read a Cluster
To read a Schema Registry Cluster, make a GET call to the cluster endpoint to retrieve details about a specified cluster. You must specify the environment and cluster identifiers in the request. This call does not require a payload. Make sure you include the authorization header with your API key and API secret.
Request example¶
GET /srcm/v2/clusters/{id}?environment={environment_id}
Your request must include the following parameters:
Parameter | Required or Optional | Description |
---|---|---|
id |
Required | Path parameter specifying the identifier for the cluster to read. |
environment |
Required | Query parameter specifying the identifier for the environment that contains the cluster to read. |
Example response¶
Success returns an HTTP 200 OK
and the following JSON payload that describes the cluster,
including the following:
- The associated Stream Governance package (ESSENTIALS or ADVANCED).
- Information about the environment that contains the cluster.
- The Schema Registry region ID.
- The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
"api_version": "srcm/v2",
"kind": "Cluster",
"id": "lsrc-12345",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Stream Governance package",
"package": "ESSENTIALS",
"http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
"environment": {
"id": "env-00000",
"related": "https://api.confluent.cloud/v2/environments/env-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
},
"region": {
"id": "sgreg-00000",
"related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
}
},
"status": {
"phase": "PROVISIONED"
}
}
Update a cluster¶
API reference link: Update a Cluster
You can update a cluster with an HTTP PATCH
call to the cluster endpoint.
You specify the environment and cluster identifiers in the request, and include
a payload that contains details of the change. You can specify one change in the request:
- Update the Stream Governance package type associated with the cluster: ESSENTIALS or ADVANCED. Note that clusters can be upgraded from ESSENTIALS to ADVANCED, but cannot be downgraded from ADVANCED to ESSENTIALS.
Make sure you include the authorization header with your API key and API secret.
Request example¶
PATCH /srcm/v2/clusters/{id}
Parameter | Required or Optional | Description |
---|---|---|
package |
Required | String identifying the package to associate with the cluster. |
environment |
Required | Object specifying the identifier for the environment that contains the cluster to update. |
The JSON payload contains a spec
object with:
- The ID for the environment that contains the Schema Registry Cluster.
- The package type to associate with the Schema Registry Cluster.
{
"spec": {
"package": "ADVANCED",
"environment": {
"id": "env-00000"
}
}
}
Example response¶
Success returns a 200 OK
and JSON payload that describes the updated cluster. Similiar to the other
calls, the payload describes:
- The associated Stream Governance package (ESSENTIALS or ADVANCED).
- Information about the environment that contains the cluster.
- The Schema Registry region ID.
- The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
"api_version": "srcm/v2",
"kind": "Cluster",
"id": "dlz-f3a90de",
"metadata": {
"self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
"resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
"created_at": "2006-01-02T15:04:05-07:00",
"updated_at": "2006-01-02T15:04:05-07:00",
"deleted_at": "2006-01-02T15:04:05-07:00"
},
"spec": {
"display_name": "Stream Governance package",
"package": "ESSENTIALS",
"http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
"environment": {
"id": "env-00000",
"related": "https://api.confluent.cloud/v2/environments/env-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
},
"region": {
"id": "sgreg-00000",
"related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
"resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
}
},
"status": {
"phase": "PROVISIONED"
}
}
Delete a cluster¶
API reference link: Delete a Cluster
You can delete a Schema Registry Cluster with a DELETE call to the cluster endpoint. You specify the environment and cluster identifiers in the request, and the call does not require a payload. Make sure you include the authorization header with your API key and API secret.
Note that once a cluster has been deleted, it cannot be restored.
Request example¶
DELETE /srcm/v2/clusters/{id}?environment={environment_id}
Parameter | Required or Optional | Description |
---|---|---|
id |
Required | Path parameter specifying the identifier for the cluster to delete. |
environment |
Required | Query parameter specifying the identifier for the environment that contains the cluster to delete. |
Failures¶
When a failure occurs, you should receive one of the following statuses:
400 Bad Request
- Typically a malformed or missing parameter or a parameter value that is not allowed.
401 Unauthorized
- Typically invalid or missing authentication credentials.
403 Forbidden
- Indicates the credentials provided are not valid for the resource. Make sure your cluster and environment identifiers are correct and match the credentials provided.
404 Not Found
- Indicates the resource could not be found at the specified URL.
429 Rate Limit Exceeded
- You have sent too many requests.
500 Oops something went wrong
- An issue not covered by other errors.
The failure message body will provide more detail about the failure reason and an identifier to use with Confluent
support if you need help solving the problem. The following example shows a 400 Bad Request
error with details about why the call failed.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"errors": [
{
"id": "c9cb03c2878ca172bbd0072bd99a9aaa",
"status": "400",
"code": "parameter_missing",
"detail": "Missing Parameter",
"source": {
"parameter": "environment"
}
}
]
}