Skip to content

REST documentation

Jump to bottom
shivesh ranjan edited this page Jun 8, 2020 · 27 revisions

Pravega Schema Registry APIs

Overview

REST APIs for Pravega Schema Registry.

Version information

Version : 0.0.1

License information

License : Apache 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
Terms of service : null

URI scheme

BasePath : /v1
Schemes : HTTP

Tags

  • Group : Group related APIs
  • Schemas : Schema related APIs

Paths

POST /groups

Description

Create a new Group

Parameters

Type Name Description Schema
Query namespace
optional 		Namespace in which to create group string
Body CreateGroupRequest
required 		The Group configuration CreateGroupRequest

CreateGroupRequest

Name Description Schema
groupName
required 		Example : "string" string
groupProperties
required 		Example : "[groupproperties](#groupproperties)" GroupProperties

Responses

HTTP Code Description Schema
201 Successfully added group No Content
409 Group with given name already exists No Content
500 Internal server error while creating a Group No Content

Consumes

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups
Request body
{
  "groupName" : "string",
  "groupProperties" : {
    "serializationFormat" : {
      "serializationFormat" : "string",
      "customTypeName" : "string"
    },
    "schemaValidationRules" : {
      "rules" : {
        "string" : "[schemavalidationrule](#schemavalidationrule)"
      }
    },
    "allowMultipleTypes" : true,
    "properties" : {
      "string" : "string"
    }
  }
}

GET /groups

Description

List all groups within the namespace. If namespace is not specified, All groups in default namespace are listed.

Parameters

Type Name Description Schema
Query continuationToken
optional 		Continuation token string
Query limit
optional 		The numbers of items to return integer
Query namespace
optional 		Namespace in which to look up groups string

Responses

HTTP Code Description Schema
200 List of all groups ListGroupsResponse
500 Internal server error while fetching the list of Groups No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups

Example HTTP response

Response 200
{
  "groups" : {
    "string" : "[groupproperties](#groupproperties)"
  },
  "continuationToken" : "string"
}

GET /groups/{groupName}

Description

Fetch the properties of an existing Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Found Group properties GroupProperties
404 Group with given name not found No Content
500 Internal server error while fetching Group details No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string

Example HTTP response

Response 200
{
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaValidationRules" : {
    "rules" : {
      "string" : "[schemavalidationrule](#schemavalidationrule)"
    }
  },
  "allowMultipleTypes" : true,
  "properties" : {
    "string" : "string"
  }
}

DELETE /groups/{groupName}

Description

Delete a Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
204 Successfully deleted the Group No Content
500 Internal server error while deleting the Group No Content

Tags

  • Group

Example HTTP request

Request path
/groups/string

POST /groups/{groupName}/codecTypes

Description

Adds a new codecType to the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body codecType
required 		The codecType string

Responses

HTTP Code Description Schema
201 Successfully added codecType to group No Content
404 Group not found No Content
500 Internal server error while registering codectype to a Group No Content

Consumes

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/codecTypes
Request body
{ }

GET /groups/{groupName}/codecTypes

Description

Get codecTypes for the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Found CodecTypes CodecTypesList
404 Group or encoding id with given name not found No Content
500 Internal server error while fetching codecTypes registered No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/codecTypes

Example HTTP response

Response 200
{
  "codecTypes" : [ "string" ]
}

PUT /groups/{groupName}/encodings

Description

Get an encoding id that uniquely identifies a schema version and codec type pair.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body GetEncodingIdRequest
required 		Get schema corresponding to the version GetEncodingIdRequest

GetEncodingIdRequest

Name Description Schema
codecType
required 		Example : "string" string
versionInfo
required 		Example : "[versioninfo](#versioninfo)" VersionInfo

Responses

HTTP Code Description Schema
200 Found Encoding EncodingId
404 Group with given name or version not found No Content
412 Codec type not registered No Content
500 Internal server error while getting encoding id No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/encodings
Request body
{
  "versionInfo" : {
    "type" : "string",
    "version" : 0,
    "ordinal" : 0
  },
  "codecType" : "string"
}

Example HTTP response

Response 200
{
  "encodingId" : 0
}

GET /groups/{groupName}/encodings/{encodingId}

Description

Get the encoding information corresponding to the encoding id.

Parameters

Type Name Description Schema
Path encodingId
required 		Encoding id that identifies a unique combination of schema and codec type integer (int32)
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Found Encoding EncodingInfo
404 Group or encoding id with given name not found No Content
500 Internal server error while getting encoding info corresponding to encoding id No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/encodings/0

Example HTTP response

Response 200
{
  "schemaInfo" : {
    "type" : "string",
    "serializationFormat" : {
      "serializationFormat" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  },
  "versionInfo" : {
    "type" : "string",
    "version" : 0,
    "ordinal" : 0
  },
  "codecType" : "string"
}

GET /groups/{groupName}/history

Description

Fetch the history of schema evolution of a Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Found Group history GroupHistory
404 Group with given name not found No Content
500 Internal server error while fetching Group history No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/history

Example HTTP response

Response 200
{
  "history" : [ {
    "schemaInfo" : {
      "type" : "string",
      "serializationFormat" : {
        "serializationFormat" : "string",
        "customTypeName" : "string"
      },
      "schemaData" : "string",
      "properties" : {
        "string" : "string"
      }
    },
    "version" : {
      "type" : "string",
      "version" : 0,
      "ordinal" : 0
    },
    "validationRules" : {
      "rules" : {
        "string" : "[schemavalidationrule](#schemavalidationrule)"
      }
    },
    "timestamp" : 0,
    "schemaString" : "string"
  } ]
}

PUT /groups/{groupName}/rules

Description

update schema validation rules of an existing Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body UpdateValidationRulesRequest
required 		update group policy UpdateValidationRulesRequest

UpdateValidationRulesRequest

Name Description Schema
previousRules
optional 		Example : "[schemavalidationrules](#schemavalidationrules)" SchemaValidationRules
validationRules
required 		Example : "[schemavalidationrules](#schemavalidationrules)" SchemaValidationRules

Responses

HTTP Code Description Schema
200 Updated schema validation policy No Content
404 Group with given name not found No Content
409 Write conflict No Content
500 Internal server error while updating Group's schema validation rules No Content

Consumes

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/rules
Request body
{
  "validationRules" : {
    "rules" : {
      "string" : "[schemavalidationrule](#schemavalidationrule)"
    }
  },
  "previousRules" : {
    "rules" : {
      "string" : "[schemavalidationrule](#schemavalidationrule)"
    }
  }
}

GET /groups/{groupName}/schemas

Description

Fetch latest schema versions for all objects identified by SchemaInfo#type under a Group. If query param type is specified then latest schema for the type is returned.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Query type
optional 		Type of object string

Responses

HTTP Code Description Schema
200 Latest schemas for all objects identified by SchemaInfo#type under the group SchemaVersionsList
404 Group with given name not found No Content
500 Internal server error while fetching Group's latest schemas No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas

Example HTTP response

Response 200
{
  "schemas" : [ {
    "schemaInfo" : {
      "type" : "string",
      "serializationFormat" : {
        "serializationFormat" : "string",
        "customTypeName" : "string"
      },
      "schemaData" : "string",
      "properties" : {
        "string" : "string"
      }
    },
    "version" : {
      "type" : "string",
      "version" : 0,
      "ordinal" : 0
    }
  } ]
}

POST /groups/{groupName}/schemas/versions

Description

Adds a new schema to the group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body schemaInfo
required 		Add new schema to group SchemaInfo

Responses

HTTP Code Description Schema
201 Successfully added schema to the group VersionInfo
404 Group not found No Content
409 Incompatible schema No Content
417 Invalid serialization format No Content
500 Internal server error while adding schema to group No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions
Request body
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

Example HTTP response

Response 201
{
  "type" : "string",
  "version" : 0,
  "ordinal" : 0
}

GET /groups/{groupName}/schemas/versions

Description

Get all schema versions for the group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Query type
optional 		Type of object the schema describes. string

Responses

HTTP Code Description Schema
200 Versioned history of schemas registered under the group SchemaVersionsList
404 Group with given name not found No Content
500 Internal server error while fetching Group schema versions No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions

Example HTTP response

Response 200
{
  "schemas" : [ {
    "schemaInfo" : {
      "type" : "string",
      "serializationFormat" : {
        "serializationFormat" : "string",
        "customTypeName" : "string"
      },
      "schemaData" : "string",
      "properties" : {
        "string" : "string"
      }
    },
    "version" : {
      "type" : "string",
      "version" : 0,
      "ordinal" : 0
    }
  } ]
}

POST /groups/{groupName}/schemas/versions/canRead

Description

Checks if given schema can be used for reads subject to compatibility policy in the schema validation rules.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body schemaInfo
required 		Checks if schema can be used to read the data in the stream based on compatibility rules. SchemaInfo

Responses

HTTP Code Description Schema
200 Response to tell whether schema can be used to read existing schemas CanRead
404 Group with given name not found No Content
500 Internal server error while checking schema for readability No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions/canRead
Request body
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

Example HTTP response

Response 200
{
  "compatible" : true
}

POST /groups/{groupName}/schemas/versions/find

Description

Get the version for the schema if it is registered. It does not automatically register the schema. To add new schema use addSchema

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body schemaInfo
required 		Get schema corresponding to the version SchemaInfo

Responses

HTTP Code Description Schema
200 Schema version VersionInfo
404 Group with given name not found No Content
500 Internal server error fetching version for schema No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions/find
Request body
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

Example HTTP response

Response 200
{
  "type" : "string",
  "version" : 0,
  "ordinal" : 0
}

POST /groups/{groupName}/schemas/versions/validate

Description

Checks if given schema is compatible with schemas in the registry for current policy setting.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string
Body ValidateRequest
required 		Checks if schema is valid with respect to supplied validation rules ValidateRequest

ValidateRequest

Name Description Schema
schemaInfo
required 		Example : "[schemainfo](#schemainfo)" SchemaInfo
validationRules
optional 		Example : "[schemavalidationrules](#schemavalidationrules)" SchemaValidationRules

Responses

HTTP Code Description Schema
200 Schema validation response Valid
404 Group with given name not found No Content
500 Internal server error while trying to validate schema No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions/validate
Request body
{
  "schemaInfo" : {
    "type" : "string",
    "serializationFormat" : {
      "serializationFormat" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  },
  "validationRules" : {
    "rules" : {
      "string" : "[schemavalidationrule](#schemavalidationrule)"
    }
  }
}

Example HTTP response

Response 200
{
  "valid" : true
}

GET /groups/{groupName}/schemas/versions/{versionOrdinal}

Description

Get schema from the version ordinal that uniquely identifies the schema in the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Path versionOrdinal
required 		Version ordinal integer (int32)
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Schema corresponding to the version SchemaInfo
404 Group with given name not found No Content
500 Internal server error while fetching schema from version No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions/0

Example HTTP response

Response 200
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

DELETE /groups/{groupName}/schemas/versions/{versionOrdinal}

Description

Delete schema identified by version from the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Path versionOrdinal
required 		Version ordinal integer (int32)
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
204 Schema corresponding to the version No Content
404 Group with given name not found No Content
500 Internal server error while deleting schema from group No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/versions/0

GET /groups/{groupName}/schemas/{type}/versions/{version}

Description

Get schema from the version ordinal that uniquely identifies the schema in the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Path type
required 		Schema type from SchemaInfo#type or VersionInfo#type string
Path version
required 		Version number integer (int32)
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
200 Schema corresponding to the version SchemaInfo
404 Group with given name not found No Content
500 Internal server error while fetching schema from version No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/string/versions/0

Example HTTP response

Response 200
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

DELETE /groups/{groupName}/schemas/{type}/versions/{version}

Description

Delete schema version from the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Path type
required 		Schema type from SchemaInfo#type or VersionInfo#type string
Path version
required 		Version number integer (int32)
Query namespace
optional 		Namespace in which to lookup group. If no namespace is specified, default namespace is used. string

Responses

HTTP Code Description Schema
204 Schema corresponding to the version No Content
404 Group with given name not found No Content
500 Internal server error while deleting schema from group No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/schemas/string/versions/0

POST /schemas/addedTo

Description

Gets a map of groups to version info where the schema if it is registered. SchemaInfo#properties is ignored while comparing the schema.

Parameters

Type Name Description Schema
Query namespace
optional 		Namespace in which to lookup schemas used in groups. If no namespace is specified, default namespace is used. string
Body schemaInfo
required 		Get schema references for the supplied schema SchemaInfo

Responses

HTTP Code Description Schema
200 Schema version AddedTo
404 Schema not found No Content
500 Internal server error while fetching Schema references No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Schemas

Example HTTP request

Request path
/schemas/addedTo
Request body
{
  "type" : "string",
  "serializationFormat" : {
    "serializationFormat" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

Example HTTP response

Response 200
{
  "groups" : {
    "string" : "[versioninfo](#versioninfo)"
  }
}

Models

ListGroupsResponse

Map of Group names to group properties. For partially created groups, the group properties may be null.

Name Type Description Required
groups object Map of Group ids to Group Properties Yes
continuationToken string Continuation token to identify the position of last group in the response. Yes

GroupProperties

Metadata for a group.

Name Type Description Required
serializationFormat SerializationFormat Serialization format for the group. Yes
schemaValidationRules SchemaValidationRules Validation rules to apply while registering new schema. Yes
allowMultipleTypes boolean Flag to indicate whether to allow multiple schemas representing distinct objects to be registered in the group. Yes
properties object User defined Key value strings. No

SerializationFormat

Serialization format enum that lists different serialization formats supported by the service. To use additional Serialization Format, use serializationFormat.Custom and supply customTypeName.

Name Type Description Required
serializationFormat string Yes
customTypeName string No

Serialization Format enum:

  - Avro
  - Protobuf
  - Json
  - Any
  - Custom

SchemaInfo

Schema information object that encapsulates various properties of a schema.

Name Type Description Required
type string Type of object described by this schema. This identifies the type of object the schema payload represents. Yes
serializationFormat SerializationFormat Type of schema. Yes
schemaData binary Base64 encoded string for binary data for schema. Yes
properties object User defined key value strings. No

VersionInfo

Version information object.

Name Type Description Required
type string Type of object described by schema identified by this version. This is the name used in SchemaInfo#type. Yes
version integer Version number that uniquely identifies the schema version among all schemas in the group that share the same type. Yes
ordinal integer Version ordinal that uniquely identifies the position of the corresponding schema across all schemas in the group. Yes

SchemaWithVersion

Object that encapsulates SchemaInfo and its corresponding VersionInfo objects.

Name Type Description Required
schemaInfo SchemaInfo Schema information. Yes
version VersionInfo Version information. Yes

SchemaVersionsList

List of schemas with their versions.

Name Type Description Required
schemas [ SchemaWithVersion ] List of schemas with their versions. No

EncodingId

Encoding id that uniquely identifies a schema version and codec pair.

Name Type Description Required
encodingId integer encoding id generated by service. Yes

EncodingInfo

Encoding information object that resolves the schema version and codec used for corresponding encoding id.

Name Type Description Required
schemaInfo SchemaInfo Schema information object. Yes
versionInfo VersionInfo Version information object. Yes
codecType String Codec type object. Yes

Compatibility

Schema Compatibility validation rule.

Name Type Description Required
name string Name is used to identify the type of SchemaValidationRule. For Compatibility rule the name should be "Compatibility". Yes
policy string Compatibility policy enum. Yes
backwardTill VersionInfo Version for backward till if policy is BackwardTill or BackwardAndForwardTill. No
forwardTill VersionInfo Version for forward till if policy is ForwardTill or BackwardAndForwardTill. No

Policy enum:

  - AllowAny
  - DenyAll
  - Backward
  - Forward
  - ForwardTransitive
  - BackwardTransitive
  - BackwardTill
  - ForwardTill
  - BackwardAndForwardTill
  - Full
  - FullTransitive

SchemaValidationRules

Schema validation rules to be applied for new schema addition. Currently only one rule is supported - Compatibility.

Name Type Description Required
rules object SchemaValidationRule No

SchemaValidationRule

Schema validation rule base class.

Name Type Description Required
rule Specific schema validation rule. The only rule we have presently is Compatibility. The "name" is used to identify specific Rule type. The only rule supported in this is Compatibility. Yes

Only rule supported currently is Compatibility.

{
	"Compatibility" : {
		"rule": {
			"name" : "Compatibility",
			"policy":[CompatibilityPolicyEnum](#compatibilitypolicyenum),
			"backwardTill" : [VersionInfo](#versioninfo),
			"forwardTill" : [VersionInfo](#versioninfo),
		}
	}
}

CodecsList

Response object for listCodecTypes.

Name Type Description Required
codecTypes [ String ] List of codecTypes. These are expressed as MIME types No

Valid

Response object for validateSchema api.

Name Type Description Required
valid boolean Whether given schema is valid with respect to existing group schemas against the configured validation rules. Yes

CanRead

Response object for canRead api.

Name Type Description Required
compatible boolean Whether given schema is compatible and can be used for reads. Compatibility is checked against existing group schemas subject to group's configured compatibility policy. Yes

GroupHistoryRecord

Group History Record that describes each schema evolution - schema information, version generated for the schema, time and rules used for schema validation.

Name Type Description Required
schemaInfo SchemaInfo Schema information object. Yes
version VersionInfo Schema version information object. Yes
validationRules SchemaValidationRules Schema validation rules applied. Yes
timestamp long Timestamp when the schema was added. Yes
schemaString string Schema as json string for serialization formats that registry service understands. No

GroupHistory

Name Type Description Required
history [ GroupHistoryRecord ] Chronological list of Group History records. No
Clone this wiki locally