Skip to content

REST documentation

Jump to bottom
shivesh ranjan edited this page May 24, 2020 · 27 revisions

Pravega Schema Registry APIs

Overview

REST APIs for Pravega Schema Registry.

Version information

Version : 0.0.1

URI scheme

BasePath : /v1
Schemes : HTTP

Tags

  • Codecs : Codecs related APIs
  • Encoding : Encoding related APIs
  • Group : Group related APIs
  • Schema : Schema related APIs

Paths

POST /groups

Description

Create a new Group

Parameters

Type Name Description Schema
Body CreateGroupRequest
required 		The Group configuration CreateGroupRequest

CreateGroupRequest

Name Description Schema
groupName
required 		Example : "string" string
properties
optional 		Example : {<br> "string" : "string"<br>} < string, string > map
schemaType
required 		Example : "[SchemaType](#SchemaType)" SchemaType
validationRules
required 		Example : "[SchemaValidationRules](#SchemaValidationRules)" SchemaValidationRules
versionedBySchemaName
required 		Example : true boolean

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",
  "schemaType" : {
    "schemaType" : "string",
    "customTypeName" : "string"
  },
  "validationRules" : {
    "rules" : {
      "string" : "[SchemaValidationRule](#SchemaValidationRule)"
    }
  },
  "properties" : {
    "string" : "string"
  },
  "versionedBySchemaName" : true
}

GET /groups

Description

List all groups

Parameters

Type Name Description Schema
Query continuationToken
optional 		Continuation token string
Query limit
optional 		The numbers of items to return integer

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

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
{
  "schemaType" : {
    "schemaType" : "string",
    "customTypeName" : "string"
  },
  "schemaValidationRules" : {
    "rules" : {
      "string" : "[SchemaValidationRule](#SchemaValidationRule)"
    }
  },
  "versionedBySchemaName" : true,
  "properties" : {
    "string" : "string"
  }
}

DELETE /groups/{groupName}

Description

Delete a Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name 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}/codecs

Description

Adds a new codec to the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Body AddCodec
required 		The codec AddCodec

AddCodec

Name Description Schema
codec
required 		Example : "[CodecType](#CodecType)" CodecType

Responses

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

Consumes

  • application/json

Tags

  • Codecs

Example HTTP request

Request path
/groups/string/codecs
Request body
{
  "codec" : {
    "codecType" : "string",
    "customTypeName" : "string",
    "properties" : {
      "string" : "string"
    }
  }
}

GET /groups/{groupName}/codecs

Description

Get codecs for the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string

Responses

HTTP Code Description Schema
200 Found Codecs CodecsList
404 Group or encoding id with given name not found No Content
500 Internal server error while fetching Group details No Content

Produces

  • application/json

Tags

  • Codecs

Example HTTP request

Request path
/groups/string/codecs

Example HTTP response

Response 200
{
  "codecTypes" : [ {
    "codecType" : "string",
    "customTypeName" : "string",
    "properties" : {
      "string" : "string"
    }
  } ]
}

PUT /groups/{groupName}/encodings

Description

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

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Body GetEncodingIdRequest
required 		Get schema corresponding to the version GetEncodingIdRequest

GetEncodingIdRequest

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • Encoding

Example HTTP request

Request path
/groups/string/encodings
Request body
{
  "versionInfo" : {
    "schemaName" : "string",
    "version" : 0,
    "ordinal" : 0
  },
  "codecType" : {
    "codecType" : "string",
    "customTypeName" : "string",
    "properties" : {
      "string" : "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 integer (int32)
Path groupName
required 		Group name 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 fetching Group details No Content

Produces

  • application/json

Tags

  • Encoding

Example HTTP request

Request path
/groups/string/encodings/0

Example HTTP response

Response 200
{
  "schemaInfo" : {
    "schemaName" : "string",
    "schemaType" : {
      "schemaType" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  },
  "versionInfo" : {
    "schemaName" : "string",
    "version" : 0,
    "ordinal" : 0
  },
  "codecType" : {
    "codecType" : "string",
    "customTypeName" : "string",
    "properties" : {
      "string" : "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

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 details No Content

Produces

  • application/json

Tags

  • Group

Example HTTP request

Request path
/groups/string/history

Example HTTP response

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

GET /groups/{groupName}/rules

Description

Fetch the schema validation rules configured for the Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string

Responses

HTTP Code Description Schema
200 Found Group schema validation rules SchemaValidationRules
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/rules

Example HTTP response

Response 200
{
  "rules" : {
    "string" : "[SchemaValidationRule](#SchemaValidationRule)"
  }
}

PUT /groups/{groupName}/rules

Description

update schema validation rules of an existing Group

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Body UpdateValidationRulesPolicyRequest
required 		update group policy UpdateValidationRulesPolicyRequest

UpdateValidationRulesPolicyRequest

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 fetching Group details 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/names

Description

Fetch all different objects identified by schema names under a Group. This api will return schema types.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string

Responses

HTTP Code Description Schema
200 List of objects identified by schema names under the group SchemaNamesList
404 Group with given name not found No Content
500 Internal server error while fetching Group details No Content

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/names

Example HTTP response

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

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 schemaName
optional 		Schema Name string
Body AddSchemaRequest
required 		Add new schema to group AddSchemaRequest

AddSchemaRequest

Name Description Schema
schemaInfo
required 		Example : "[SchemaInfo](#SchemaInfo)" 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 schema type No Content
500 Internal server error while creating a Group No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions
Request body
{
  "schemaInfo" : {
    "schemaName" : "string",
    "schemaType" : {
      "schemaType" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  }
}

Example HTTP response

Response 201
{
  "schemaName" : "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 schemaName
optional 		Schema Name 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 details No Content

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions

Example HTTP response

Response 200
{
  "schemas" : [ {
    "schemaInfo" : {
      "schemaName" : "string",
      "schemaType" : {
        "schemaType" : "string",
        "customTypeName" : "string"
      },
      "schemaData" : "string",
      "properties" : {
        "string" : "string"
      }
    },
    "version" : {
      "schemaName" : "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
Body CanReadRequest
required 		Checks if schema can be used to read the data in the stream based on compatibility rules. CanReadRequest

CanReadRequest

Name Description Schema
schemaInfo
required 		Example : "[SchemaInfo](#SchemaInfo)" SchemaInfo

Responses

HTTP Code Description Schema
200 Schema can be used to read No Content
404 Group with given name not found No Content
500 Internal server error while fetching Group details No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions/canRead
Request body
{
  "schemaInfo" : {
    "schemaName" : "string",
    "schemaType" : {
      "schemaType" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  }
}

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

Description

Get latest schema for the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Query schemaName
optional 		Schema Name string

Responses

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

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions/latest

Example HTTP response

Response 200
{
  "schemaInfo" : {
    "schemaName" : "string",
    "schemaType" : {
      "schemaType" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  },
  "version" : {
    "schemaName" : "string",
    "version" : 0,
    "ordinal" : 0
  }
}

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

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
Body GetSchemaVersion
required 		Get schema corresponding to the version GetSchemaVersion

GetSchemaVersion

Name Description Schema
schemaInfo
required 		Example : "[SchemaInfo](#SchemaInfo)" SchemaInfo

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions/search
Request body
{
  "schemaInfo" : {
    "schemaName" : "string",
    "schemaType" : {
      "schemaType" : "string",
      "customTypeName" : "string"
    },
    "schemaData" : "string",
    "properties" : {
      "string" : "string"
    }
  }
}

Example HTTP response

Response 200
{
  "schemaName" : "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
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 is valid No Content
404 Group with given name not found No Content
500 Internal server error while fetching Group details No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • Schema

Example HTTP request

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

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 version
required 		Version ordinal integer (int32)

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 Group details No Content

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions/{versionOrdinal}

Example HTTP response

Response 200
{
  "schemaName" : "string",
  "schemaType" : {
    "schemaType" : "string",
    "customTypeName" : "string"
  },
  "schemaData" : "string",
  "properties" : {
    "string" : "string"
  }
}

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

Description

Delete schema version from the group.

Parameters

Type Name Description Schema
Path groupName
required 		Group name string
Path version
required 		Version ordinal integer (int32)

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 fetching Group details No Content

Produces

  • application/json

Tags

  • Schema

Example HTTP request

Request path
/groups/string/schemas/versions/{versionOrdinal}

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 No
continuationToken string Continuation token to identify the position of last group in the response. Yes

SchemaNamesList

List of schema names. Schema names uniquely identify different object types under a group.

Name Type Description Required
objects [ string ] No

GroupProperties

Metadata for a group.

Name Type Description Required
schemaType SchemaType Schema type for the group. Yes
schemaValidationRules SchemaValidationRules Validation rules to apply while registering new schema. Yes
versionedBySchemaName boolean Flag to indicate whether to version schemas within the group by schema name. If set to true, addSchema will only validate against schemas that have the same schema name. Yes
properties object User defined Key value strings. No

SchemaType

Schema type enum that lists different schema types supported by the service. To use additional Schema Type, use schemaType.Custom and supply customTypeName.

Name Type Description Required
schemaType string Yes
customTypeName string No

Schema Type enum:

  - Avro
  - Protobuf
  - Json
  - Any
  - Custom

SchemaInfo

Schema information object that encapsulates various properties of a schema.

Name Type Description Required
schemaName string Name of the schema. This identifies the type of object the schema payload represents. Yes
schemaType SchemaType 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
schemaName string Name of schema for this version. This is the name used in SchemaInfo.schemaName. Yes
version integer Version number that uniquely identifies the schema version among all schemas in the group that share the same SchemaName. 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

CodecType

Type of codec. For custom codec use codecType.Custom with customTypeName and optionally additional properties.

Name Type Description Required
codecType string Code Type enum. Yes
customTypeName string Custom type name when codecType.custom is chosen. No
properties object Optional additional key value string for codecType.cusom. No

Codec Type enum:

  - None
  - Snappy
  - Gzip
  - Custom

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 CodecType 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 [ CodecType ] List of codecTypes. 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 schema types that registry service understands. No

GroupHistory

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