Skip to content

REST documentation

Jump to bottom
shivesh ranjan edited this page May 14, 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

  • Group : Group related APIs
  • Schema : Schema related APIs
  • Encoding : Encoding 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
optional 		Example : "string" string
properties
optional 		Example : {<br> "string" : "string"<br>} < string, string > map
schemaType
optional 		Example : "[schematype](#schematype)" SchemaType
validationRules
optional 		Example : "[schemavalidationrules](#schemavalidationrules)" SchemaValidationRules
versionBySchemaName
optional 		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"
  },
  "versionBySchemaName" : 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
{
  "schemaValidationRules" : {
    "rules" : {
      "string" : "[schemavalidationrule](#schemavalidationrule)"
    }
  },
  "schemaType" : {
    "schemaType" : "string",
    "customTypeName" : "string"
  },
  "versionBySchemaName" : 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
optional 		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

  • Group

Example HTTP request

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

GET /groups/{groupName}/codecs

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 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

  • Encoding

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

Fetch the properties of an existing Group

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
optional 		Example : "[codectype](#codectype)" CodecType
versionInfo
optional 		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

Fetch the properties of an existing Group

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 properties of an existing 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
optional 		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

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

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
Body AddSchemaToGroupRequest
required 		Add new schema to group AddSchemaToGroupRequest

AddSchemaToGroupRequest

Name Description Schema
schemaInfo
optional 		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

Fetch the properties of an existing Group

Parameters

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

check 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
optional 		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

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 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/validate

Description

check 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
optional 		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)"
    }
  }
}

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

Description

Get the version for the schema if it is registered.

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
optional 		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/version
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
}

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

Description

Fetch the properties of an existing 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"
  }
}

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

Description

Fetch all schemas registered with the given schema name

Parameters

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

Responses

HTTP Code Description Schema
200 Versioned history of schemas registered under the group of specified schema type 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/string/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
    }
  } ]
}

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

Description

Fetch the properties of an existing Group

Parameters

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

Responses

HTTP Code Description Schema
200 Found latest schema in name 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/string/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
  }
}
Clone this wiki locally