Rest API

Register Schema

POST /subjects/$SUBJECT/versions?normalize=[true/false]

Registers the schema under given $SUBJECT only if the new schema is compatible.

normalize is false by default. If passed, the schema will be normalized. Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/$SUBJECT/versions -u myuser:mypass -d '
{
  "schema": "{
    \"type\": \"record\",
    \"name\": \"myRecord\",
    \"fields\":
        [
        {\"type\": \"string\",\"name\": \"field1\"},
        {\"type\": \"int\"   ,\"name\": \"field2\"}
        ]
  }",
  "schemaType": "AVRO"
}'

Success Response:

The schema ID returned as the response:

{"id" : 2}

Fail Response:

- 409 Conflict – Incompatible schema
- 422 Unprocessable Entity
  - Error code 42201 – Invalid schema
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Check schema

POST /subjects/$SUBJECT?normalize=[true/false]&deleted=[true/false]

Check if the given schema is registered under the $SUBJECT. Returns the schema along with subject, version, and schema type.

normalize is false by default. If set to true, the schema will be normalized. Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.

deleted is false by default. If set to true, the soft-deleted schemas under the subject will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/my-subject/$SUBJECT -u myuser:mypass -d '
{
  "schema": "{
    \"type\": \"record\",
    \"name\": \"myRecord\",
    \"fields\":
        [
        {\"type\": \"string\",\"name\": \"field1\"},
        {\"type\": \"int\"   ,\"name\": \"field2\"}
        ]
  }",
  "schemaType": "AVRO"
}'

**Success Response:**

```json
{
      "subject": "my-subject",
      "id": 2
      "version": 3
      "schema":
         "
          {
            "schema": "{
              \"type\": \"record\",
              \"name\": \"myRecord\",
              \"fields\":
                  [
                  {\"type\": \"string\",\"name\": \"field1\"},
                  {\"type\": \"int\"   ,\"name\": \"field2\"}
                  ]
            }",
            "schemaType": "AVRO"
          }
         "
    }

Fail Response

- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Set Config

PUT /config

Sets the global compatibility. Global compatibility is effective if a subject is not assigned a compatibility by default. See Compatibility for options.

curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass -d '
{
  "compatibility" : "FULL"
}'

PUT /config/$SUBJECT

Sets the compatibility of a subject. See Compatibility for options.

curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass -d '
{
  "compatibility" : "FULL"
}'

Success Response:

{
  "compatibilityLevel" : "FULL"
}

Fail Response

- 500 Internal Server Error
    - Error code 50001 – Error in the backend data store
    - Error code 50002 – Operation timed out
    - Error code 50003 – Error while forwarding the request to the primary

Get Config

GET /config

Retrieves the global config. Note that the default global config is BACKWARD_TRANSITIVE by default if not set.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass

GET /config/$SUBJECT?defaultToGlobal=[true/false]

Retrieves the config of the given $SUBJECT.

defaultToGlobal is false by default. When set to true, this endpoint will show the effective compatibility on a register operation. When set to false, it may return 404 Not found if a subject level compatibility is not set.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass

Success Response:

{
  "compatibilityLevel" : "FULL"
}

Fail Response

- 404 Not Found – Subject not found
- 500 Internal Server Error
    - Error code 50001 – Error in the backend data store
    - Error code 50002 – Operation timed out
    - Error code 50003 – Error while forwarding the request to the primary

Get All Schemas

GET /schemas?deleted=[false/true]

Returns all schemas registered under subjects. Note that this endpoint will return the same schema multiple times if the same schema registered under different subjects.

deleted is false by default. If set to true, the soft-deleted schemas under the subject will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schemas -u myuser:mypass

Success Response:

[
  {
    "subject": "subject1",
    "version": 1,
    "id": 1,
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
  },
  {
    "subject": "subject2",
    "version": 1,
    "id": 2,
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"string\",\"default\":\"x\"}]}"
  }
]

Fail Response

- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Get Schema With SchemaId

GET /schemas/ids/$SCHEMA_ID

Returns the schema corresponding to the given $SCHEMA_ID.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1 -u myuser:mypass

Success Response:

{
  "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}

Fail Response

- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

GET /schemas/ids/$SCHEMA_ID/schema

Returns the schema corresponding to the given $SCHEMA_ID. Additionally unwraps the inner schema field.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1/schema -u myuser:mypass

Success Response:

{
  "type": "record",
  "name": "test",
  "fields": [
    {
      "name": "field1",
      "type": "string"
    }
  ]
}

Fail Response

- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Get Schema With Subject And Version

GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]

Returns the schema with its metadata corresponding to the given $SUBJECT and $VERSION. VERSION could be an int or string latest.

deleted is false by default. If set to true, the soft-deleted schemas under the subject will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1 -u myuser:mypass

Success Response:

{
  "subject": "s1",
  "version": 1,
  "id": 1,
  "schemaType": "AVRO",
  "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}

Fail Response

- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]

Returns only the schema corresponding to the given $SUBJECT and $VERSION. VERSION could be an int or string latest.

deleted is false by default. If set to true, the soft-deleted schemas under the subject will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1/schema -u myuser:mypass

Success Response:

{
  "type": "record",
  "name": "test",
  "fields": [
    {
      "name": "field1",
      "type": "string"
    }
  ]
}

Fail Response

- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40402 – Version not found
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Get All Subjects

GET /subjects?deleted=[false/true]

Returns all subjects.

deleted is false by default. If set to true, the soft-deleted subjects will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects -u myuser:mypass

Success Response:

["subject1","subject2"]

Fail Response

- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Get Subject Versions

GET /subjects/$SUBJECT/versions?deleted=[false/true]

Returns the versions of the given $SUBJECT.

deleted is false by default. If set to true, the soft-deleted subject versions will also be taken into account. See Delete Subject or Delete Schema for details.

curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions -u myuser:mypass

Success Response:

[ 1, 2 ]

Fail Response

- 404 Not Found
  - Error code 40401 – Subject not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Delete Subject

DELETE /subjects/$SUBJECT?permanent=[true/false]

Deletes the given $SUBJECT. Returns the deleted versions as the response.

This endpoint should rarely be needed in production and needs to be used with caution. The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.

permanent is false by default. In this case, the subject only will be soft-deleted. The corresponding schemas and schema-ids will not be deleted. Any serializer/deserializer needing these schemas still will be able to use them.

if permanent is set to true. The schemas and schema-ids will also be deleted from the system only if these schemas are not registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.

Note that a subject can not be permanently deleted before it is soft-deleted.

curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject -u myuser:mypass

Success Response:

Returns the deleted versions as the response.

[1, 2, 3]

Fail Response:

- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40404 - Subject '$SUBJECT' was soft deleted. Set permanent=true to delete permanently
  - Error code 40405 - Subject '$SUBJECT' was not deleted first before being permanently deleted
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary

Delete Schema

DELETE /subjects/$SUBJECT/versions/$VERSION?permanent=[true/false]

Deletes the schema corresponding to the $SUBJECT and $VERSION. Returns the version as the response. VERSION could be an int or string latest.

This endpoint should rarely be needed in production and needs to be used with caution. The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.

permanent is false by default. In this case, the subject-version only will be soft-deleted. The corresponding schema and schema-id will not be deleted. Any serializer/deserializer needing this schema still will be able to use them.

if permanent is set to true. The schema and schema-id will also be deleted from the system only if this schema is not registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.

Note that a subject-version can not be permanently deleted before it is soft-deleted.

curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject/versions/2 -u myuser:mypass

Success Response:

Returns the deleted version as the response.

1

Fail Response:

- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40402 – Version not found
  - Error code 40406 - Subject '$SUBJECT' Version $VERSION was soft deleted. Set permanent=true to delete permanently
  - Error code 40407 - Subject '$SUBJECT' Version $VERSION was not deleted first before being permanently deleted
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary