Schema Registry API

The Azure Event Hubs Schema Registry is a fully managed service that allows you to store and manage event schemas for your event streams. This enables producers and consumers to agree on a common schema format, ensuring data consistency and enabling schema evolution. This section details the REST API for interacting with the Schema Registry.

Note: The Schema Registry API is typically accessed programmatically. While this document outlines the API endpoints and request/response structures, you will usually interact with it via SDKs or custom clients.

API Endpoints

Register Schema

Registers a new schema with the Schema Registry.

GET POST PUT DELETE /schemas/{schemaName}?api-version={api-version}

Request Body (POST/PUT)

The request body should contain the schema definition in JSON format.

{
  "schemaType": "Avro",
  "schema": "{\"type\": \"record\", \"name\": \"MyEvent\", \"fields\": [{\"name\": \"timestamp\", \"type\": \"long\"}, {\"name\": \"payload\", \"type\": \"string\"}]}"
}

Query Parameters

Name	Type	Description	Required
`api-version`	string	The API version to use. Example: `2021-10-01`	Yes

Responses

200 OK: Schema registered successfully. The response body contains the schema ID.

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

400 Bad Request: Invalid request payload or schema definition.

409 Conflict: A schema with the same name and content already exists.

Get Schema

Retrieves a specific schema from the Schema Registry.

GET /schemas/{schemaName}/{schemaVersion}?api-version={api-version}

Query Parameters

Name	Type	Description	Required
`api-version`	string	The API version to use. Example: `2021-10-01`	Yes

Responses

200 OK: Schema retrieved successfully. The response body contains the schema definition.

{
  "schemaType": "Avro",
  "schema": "{\"type\": \"record\", \"name\": \"MyEvent\", \"fields\": [{\"name\": \"timestamp\", \"type\": \"long\"}, {\"name\": \"payload\", \"type\": \"string\"}]}"
}

404 Not Found: The specified schema or version does not exist.

List Schemas

Lists all schemas or schemas for a given name.

GET /schemas?api-version={api-version}

Or, to list versions of a specific schema:

/schemas/{schemaName}?api-version={api-version}

Query Parameters

Name	Type	Description	Required
`api-version`	string	The API version to use. Example: `2021-10-01`	Yes

Responses

200 OK: A list of schemas (or schema versions) is returned.

[
  {
    "name": "MyEvent",
    "version": 1,
    "schemaType": "Avro",
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  },
  {
    "name": "MyEvent",
    "version": 2,
    "schemaType": "Avro",
    "id": "f0e9d8c7-b6a5-4321-9876-543210fedcba"
  }
]

400 Bad Request: Invalid query parameters.

Delete Schema

Deletes a specific schema version or an entire schema name.

DELETE /schemas/{schemaName}/{schemaVersion}?api-version={api-version}

To delete all versions of a schema name:

/schemas/{schemaName}?api-version={api-version}

Query Parameters

Name	Type	Description	Required
`api-version`	string	The API version to use. Example: `2021-10-01`	Yes

Responses

204 No Content: Schema deleted successfully.

404 Not Found: The specified schema or version does not exist.

Common Headers

Requests to the Schema Registry API typically include the following headers:

Header	Description
`Authorization`	Azure AD token for authentication.
`Content-Type`	`application/json` for request bodies.

Schema Types

The Schema Registry supports several schema types, including:

Avro: A data serialization system.
JSON Schema: A vocabulary that allows you to annotate and validate JSON documents.
Protobuf: Protocol Buffers, a language-neutral, platform-neutral, extensible mechanism for serializing structured data.

Error Handling

The Schema Registry API uses standard HTTP status codes to indicate the success or failure of a request. Error responses typically include a JSON body with more details:

{
  "code": "SchemaNotFound",
  "message": "The schema with name 'MyNonExistentSchema' was not found."
}