CtrlK
BlogDocsLog inGet started
Tessl Logo

gamussa/schema-registry

Schema Registry for Apache Kafka - covers schema management (Avro, Protobuf, JSON Schema), compatibility modes, schema evolution, REST API, serializer/deserializer configuration, Kafka Connect converters, Flink SQL integration, and Confluent Cloud.

100

Review — 100%

Does it follow best practices?

Validation — 11 / 11 Passed

Validation for skill structure

Overview
Skills
Evals
Files

rest-api.mddocs/

Schema Registry REST API Reference

Table of Contents

  1. General Information
  2. Schemas Endpoints
  3. Subjects Endpoints
  4. Compatibility Endpoints
  5. Config Endpoints
  6. Mode Endpoints

General Information

Base URL: http://localhost:8081 (default)

Content Type: application/vnd.schemaregistry.v1+json

Authentication (Confluent Cloud):

curl -u <API_KEY>:<API_SECRET> https://<SR_ENDPOINT>

Error Response Format:

{
  "error_code": 42201,
  "message": "Schema being registered is incompatible with an earlier schema"
}

Common error codes:

  • 40401 — Subject not found
  • 40402 — Version not found
  • 40403 — Schema not found
  • 42201 — Invalid schema
  • 42202 — Invalid version
  • 409 — Incompatible schema

Schemas Endpoints

Get Schema by ID

GET /schemas/ids/{id}

curl http://localhost:8081/schemas/ids/1

# Response
{
  "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[...]}"
}

Get Schema by ID (specific format)

GET /schemas/ids/{id}?format=serialized

Get Schema Types

GET /schemas/types

curl http://localhost:8081/schemas/types

# Response
["AVRO", "PROTOBUF", "JSON"]

Get Schema Versions by ID

GET /schemas/ids/{id}/versions

# Response — lists subjects and versions using this schema
[
  {"subject": "my-topic-value", "version": 1}
]

Subjects Endpoints

List All Subjects

GET /subjects

curl http://localhost:8081/subjects

# Response
["my-topic-key", "my-topic-value", "orders-value"]

List Versions Under a Subject

GET /subjects/{subject}/versions

curl http://localhost:8081/subjects/my-topic-value/versions

# Response
[1, 2, 3]

Get Schema by Subject and Version

GET /subjects/{subject}/versions/{version}

# {version} can be an integer or "latest"
curl http://localhost:8081/subjects/my-topic-value/versions/latest

# Response
{
  "subject": "my-topic-value",
  "id": 1,
  "version": 1,
  "schemaType": "AVRO",
  "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[...]}"
}

Register a New Schema Under a Subject

POST /subjects/{subject}/versions

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{
    "schema": "{\"type\":\"record\",\"name\":\"User\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"string\"}]}"
  }' \
  http://localhost:8081/subjects/my-topic-value/versions

# Response
{"id": 1}

For Protobuf:

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{
    "schemaType": "PROTOBUF",
    "schema": "syntax = \"proto3\"; message User { int32 id = 1; string name = 2; }"
  }' \
  http://localhost:8081/subjects/my-topic-value/versions

For JSON Schema:

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{
    "schemaType": "JSON",
    "schema": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"]}"
  }' \
  http://localhost:8081/subjects/my-topic-value/versions

With Schema References:

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{
    "schema": "...",
    "schemaType": "AVRO",
    "references": [
      {
        "name": "com.example.Address",
        "subject": "address-value",
        "version": 1
      }
    ]
  }' \
  http://localhost:8081/subjects/my-topic-value/versions

Check if Schema is Registered Under Subject

POST /subjects/{subject}

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "..."}' \
  http://localhost:8081/subjects/my-topic-value

# Response (if registered)
{
  "subject": "my-topic-value",
  "id": 1,
  "version": 1,
  "schema": "..."
}

Delete Subject (all versions)

DELETE /subjects/{subject}

curl -X DELETE http://localhost:8081/subjects/my-topic-value

# Response — list of deleted versions
[1, 2, 3]

Delete Specific Version

DELETE /subjects/{subject}/versions/{version}

curl -X DELETE http://localhost:8081/subjects/my-topic-value/versions/1

# Response
1

Permanent Delete (hard delete)

# First soft-delete, then hard-delete with ?permanent=true
DELETE /subjects/{subject}?permanent=true
DELETE /subjects/{subject}/versions/{version}?permanent=true

Compatibility Endpoints

Test Compatibility Against a Specific Version

POST /compatibility/subjects/{subject}/versions/{version}

curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "..."}' \
  http://localhost:8081/compatibility/subjects/my-topic-value/versions/latest

# Response
{"is_compatible": true}

# With verbose mode for details on failures
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "..."}' \
  "http://localhost:8081/compatibility/subjects/my-topic-value/versions/latest?verbose=true"

# Response (incompatible)
{
  "is_compatible": false,
  "messages": [
    "Incompatibility{type:READER_FIELD_MISSING_DEFAULT_VALUE, ...}"
  ]
}

Test Compatibility Against All Versions

POST /compatibility/subjects/{subject}/versions

# Same request format, tests against all versions based on configured compatibility

Query Parameters:

  • verbose=true — Returns detailed incompatibility messages
  • normalize=true — Normalizes schema before checking

Config Endpoints

Get Global Compatibility Level

GET /config

curl http://localhost:8081/config

# Response
{"compatibilityLevel": "BACKWARD"}

Update Global Compatibility Level

PUT /config

curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility": "FULL"}' \
  http://localhost:8081/config

# Response
{"compatibility": "FULL"}

Get Subject-Level Compatibility

GET /config/{subject}

curl http://localhost:8081/config/my-topic-value

# With fallback to global if not set
curl "http://localhost:8081/config/my-topic-value?defaultToGlobal=true"

Update Subject-Level Compatibility

PUT /config/{subject}

curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility": "NONE"}' \
  http://localhost:8081/config/my-topic-value

Delete Subject-Level Compatibility (revert to global)

DELETE /config/{subject}

Mode Endpoints

Get Global Mode

GET /mode

# Response
{"mode": "READWRITE"}

Modes: READWRITE (default), READONLY, READONLY_OVERRIDE, IMPORT

Set Global Mode

PUT /mode

curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"mode": "READONLY"}' \
  http://localhost:8081/mode

Get/Set Subject-Level Mode

GET /mode/{subject}
PUT /mode/{subject}

Install with Tessl CLI

npx tessl i gamussa/schema-registry

docs

confluent-cloud.md

flink-sql.md

fundamentals.md

index.md

rest-api.md

serdes.md

tile.json