List subject versions

You can list the versions of a subject within a specific schema registry in your project.

This document shows you how to list subject versions using the Google Cloud console or the Managed Kafka API.

Required roles and permissions

To get the permissions that you need to list subject versions, ask your administrator to grant you the Managed Kafka Schema Registry Viewer (roles/managedkafka.schemaRegistryViewer) IAM role on your schema registry. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to list subject versions. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to list subject versions:

  • Grant the following permission on the parent subject: managedkafka.versions.list

You might also be able to get these permissions with custom roles or other predefined roles.

For more information about predefined roles, see the Managed Service for Apache Kafka predefined roles.

List the schema versions in a subject

To list all versions of a subject in a specific schema registry within your project, follow these steps.

Console

  1. In the Google Cloud console, go to the Schema registries page.

    Go to Schema registries

  2. Click the name of the schema registry where your subject is located.

  3. Under Subjects in this schema registry, click the name of the subject.

  4. In the Subject details page, the schema versions are listed under All Versions.

  5. Optional: To view the schema definition for a version, select the checkbox for the version ID. The schema definition is shown under Definition.

  6. Optional: To view the differences between any two schema versions for this subject, perform the following steps:

    1. Under All versions, select the versions to compare.
    2. In the Definition area, click View diff.

    The two schema definitions are displayed side by side, with additions, deletions, and changes highlighted.

REST

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

To list subject versions, make a GET request to the projects.locations.schemaRegistries.subjects.versions.list method.

GET https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • LOCATION: the Google Cloud region where the schema registry is located.
  • REGISTRY_ID: the ID of your schema registry.
  • SUBJECT_ID: the ID of the subject.

Example:

GET https://managedkafka.googleapis.com/v1main/projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Or with a context:

GET https://managedkafka.googleapis.com/v1main/projects/test-project/locations/us-central1/schemaRegistries/test_registry/contexts/test_context/subjects/test_subject/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)

Where:

  • test-project is your Google Cloud project ID.
  • us-central1 is the Google Cloud region where the schema registry is located.
  • test_registry is the ID of your schema registry.
  • test_context is the ID of the context.
  • test_subject is the ID of the subject.

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of subject versions.

The following is a sample successful response:

{
  "versions": [
    {
      "name": "projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions/1",
      "revisionId": "1a2b3c4d",
      "schemaId": "S12345",
      "createTime": "2024-07-15T12:00:00Z",
      "revisionCreateTime": "2024-07-15T12:00:00Z"
    },
    {
      "name": "projects/test-project/locations/us-central1/schemaRegistries/test_registry/subjects/test_subject/versions/2",
      "revisionId": "5e6f7g8h",
      "schemaId": "S67890",
      "createTime": "2024-07-16T14:30:00Z",
      "revisionCreateTime": "2024-07-16T14:30:00Z"
    }
  ]
}

For more information, see the projects.locations.schemaRegistries.subjects.versions.list method documentation.

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.