Pravega Controller REST API¶

Overview¶

List of admin REST APIs for the Pravega Controller service.

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¶

ReaderGroups : Reader group related APIs
Scopes : Scope related APIs
Streams : Stream related APIs

Paths¶

POST /scopes¶

Description¶

Create a new scope

Parameters¶

Type	Name	Description	Schema
Body	CreateScopeRequest required	The scope configuration	CreateScopeRequest

CreateScopeRequest

Name	Description	Schema
scopeName optional	Example : `"string"`	string

Responses¶

HTTP Code	Description	Schema
201	Successfully created the scope	ScopeProperty
409	Scope with the given name already exists	No Content
500	Internal server error while creating a scope	No Content

Consumes¶

application/json

Produces¶

application/json

Tags¶

Scopes

Example HTTP request¶

Request path¶

/scopes

Request body¶

{
  "scopeName" : "string"
}

Example HTTP response¶

Response 201¶

{
  "scopeName" : "string"
}

GET /scopes¶

Description¶

List all available scopes in pravega

Responses¶

HTTP Code	Description	Schema
200	List of currently available scopes	ScopesList
500	Internal server error while fetching list of scopes	No Content

Produces¶

application/json

Tags¶

Scopes

Example HTTP request¶

Request path¶

/scopes

Example HTTP response¶

Response 200¶

{
  "scopes" : [ {
    "scopeName" : "string"
  } ]
}

GET /scopes/{scopeName}¶

Description¶

Retrieve details of an existing scope

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string

Responses¶

HTTP Code	Description	Schema
200	Successfully retrieved the scope details	ScopeProperty
404	Scope with the given name not found	No Content
500	Internal server error while fetching scope details	No Content

Produces¶

application/json

Tags¶

Scopes

Example HTTP request¶

Request path¶

/scopes/string

Example HTTP response¶

Response 200¶

{
  "scopeName" : "string"
}

DELETE /scopes/{scopeName}¶

Description¶

Delete a scope

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string

Responses¶

HTTP Code	Description	Schema
204	Successfully deleted the scope	No Content
404	Scope not found	No Content
412	Cannot delete scope since it has non-empty list of streams	No Content
500	Internal server error while deleting a scope	No Content

Tags¶

Scopes

Example HTTP request¶

Request path¶

/scopes/string

GET /scopes/{scopeName}/readergroups¶

Description¶

List reader groups within the given scope

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string

Responses¶

HTTP Code	Description	Schema
200	List of all reader groups configured for the given scope	ReaderGroupsList
404	Scope not found	No Content
500	Internal server error while fetching the list of reader groups for the given scope	No Content

Produces¶

application/json

Tags¶

ReaderGroups

Example HTTP request¶

Request path¶

/scopes/string/readergroups

Example HTTP response¶

Response 200¶

{
  "readerGroups" : [ "object" ]
}

GET /scopes/{scopeName}/readergroups/{readerGroupName}¶

Description¶

Fetch the properties of an existing reader group

Parameters¶

Type	Name	Description	Schema
Path	readerGroupName required	Reader group name	string
Path	scopeName required	Scope name	string

Responses¶

HTTP Code	Description	Schema
200	Found reader group properties	ReaderGroupProperty
404	Scope or reader group with given name not found	No Content
500	Internal server error while fetching reader group details	No Content

Produces¶

application/json

Tags¶

ReaderGroups

Example HTTP request¶

Request path¶

/scopes/string/readergroups/string

Example HTTP response¶

Response 200¶

{
  "scopeName" : "string",
  "readerGroupName" : "string",
  "streamList" : [ "string" ],
  "onlineReaderIds" : [ "string" ]
}

POST /scopes/{scopeName}/streams¶

Description¶

Create a new stream

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Body	CreateStreamRequest required	The stream configuration	CreateStreamRequest

CreateStreamRequest

Name	Description	Schema
retentionPolicy optional	Example : `"[retentionconfig](#retentionconfig)"`	RetentionConfig
scalingPolicy optional	Example : `"[scalingconfig](#scalingconfig)"`	ScalingConfig
streamName optional	Example : `"string"`	string

Responses¶

HTTP Code	Description	Schema
201	Successfully created the stream with the given configuration	StreamProperty
404	Scope not found	No Content
409	Stream with given name already exists	No Content
500	Internal server error while creating a stream	No Content

Consumes¶

application/json

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams

Request body¶

{
  "streamName" : "string",
  "scalingPolicy" : {
    "type" : "string",
    "targetRate" : 0,
    "scaleFactor" : 0,
    "minSegments" : 0
  },
  "retentionPolicy" : {
    "type" : "string",
    "value" : 0,
    "timeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  }
}

Example HTTP response¶

Response 201¶

{
  "scopeName" : "string",
  "streamName" : "string",
  "scalingPolicy" : {
    "type" : "string",
    "targetRate" : 0,
    "scaleFactor" : 0,
    "minSegments" : 0
  },
  "retentionPolicy" : {
    "type" : "string",
    "value" : 0,
    "timeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  }
}

GET /scopes/{scopeName}/streams¶

Description¶

List streams within the given scope

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Query	showInternalStreams optional	Optional flag whether to display system created streams. If not specified only user created streams will be returned	string

Responses¶

HTTP Code	Description	Schema
200	List of all streams configured for the given scope	StreamsList
404	Scope not found	No Content
500	Internal server error while fetching the list of streams for the given scope	No Content

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams

Example HTTP response¶

Response 200¶

{
  "streams" : [ {
    "scopeName" : "string",
    "streamName" : "string",
    "scalingPolicy" : {
      "type" : "string",
      "targetRate" : 0,
      "scaleFactor" : 0,
      "minSegments" : 0
    },
    "retentionPolicy" : {
      "type" : "string",
      "value" : 0,
      "timeBasedRetention" : {
        "days" : 0,
        "hours" : 0,
        "minutes" : 0
      }
    }
  } ]
}

GET /scopes/{scopeName}/streams/{streamName}¶

Description¶

Fetch the properties of an existing stream

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Path	streamName required	Stream name	string

Responses¶

HTTP Code	Description	Schema
200	Found stream properties	StreamProperty
404	Scope or stream with given name not found	No Content
500	Internal server error while fetching stream details	No Content

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams/string

Example HTTP response¶

Response 200¶

{
  "scopeName" : "string",
  "streamName" : "string",
  "scalingPolicy" : {
    "type" : "string",
    "targetRate" : 0,
    "scaleFactor" : 0,
    "minSegments" : 0
  },
  "retentionPolicy" : {
    "type" : "string",
    "value" : 0,
    "timeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  }
}

PUT /scopes/{scopeName}/streams/{streamName}¶

Description¶

Update configuration of an existing stream

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Path	streamName required	Stream name	string
Body	UpdateStreamRequest required	The new stream configuration	UpdateStreamRequest

UpdateStreamRequest

Name	Description	Schema
retentionPolicy optional	Example : `"[retentionconfig](#retentionconfig)"`	RetentionConfig
scalingPolicy optional	Example : `"[scalingconfig](#scalingconfig)"`	ScalingConfig

Responses¶

HTTP Code	Description	Schema
200	Successfully updated the stream configuration	StreamProperty
404	Scope or stream with given name not found	No Content
500	Internal server error while updating the stream	No Content

Consumes¶

application/json

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams/string

Request body¶

{
  "scalingPolicy" : {
    "type" : "string",
    "targetRate" : 0,
    "scaleFactor" : 0,
    "minSegments" : 0
  },
  "retentionPolicy" : {
    "type" : "string",
    "value" : 0,
    "timeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  }
}

Example HTTP response¶

Response 200¶

{
  "scopeName" : "string",
  "streamName" : "string",
  "scalingPolicy" : {
    "type" : "string",
    "targetRate" : 0,
    "scaleFactor" : 0,
    "minSegments" : 0
  },
  "retentionPolicy" : {
    "type" : "string",
    "value" : 0,
    "timeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  }
}

DELETE /scopes/{scopeName}/streams/{streamName}¶

Description¶

Delete a stream

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Path	streamName required	Stream name	string

Responses¶

HTTP Code	Description	Schema
204	Successfully deleted the stream	No Content
404	Stream not found	No Content
412	Cannot delete stream since it is not sealed	No Content
500	Internal server error while deleting the stream	No Content

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams/string

GET /scopes/{scopeName}/streams/{streamName}/scaling-events¶

Description¶

Get scaling events for a given datetime period.

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Path	streamName required	Stream name	string
Query	from required	Parameter to display scaling events from that particular datetime. Input should be milliseconds from Jan 1 1970.	integer (int64)
Query	to required	Parameter to display scaling events to that particular datetime. Input should be milliseconds from Jan 1 1970.	integer (int64)

Responses¶

HTTP Code	Description	Schema
200	Successfully fetched list of scaling events.	ScalingEventList
404	Scope/Stream not found.	No Content
500	Internal Server error while fetching scaling events.	No Content

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams/string/scaling-events?from=0&to=0

Example HTTP response¶

Response 200¶

{
  "scalingEvents" : [ {
    "timestamp" : 0,
    "segmentList" : [ {
      "number" : 0,
      "startTime" : 0,
      "keyStart" : 0,
      "keyEnd" : 0
    } ],
    "splits" : 0,
    "merges" : 0
  } ]
}

PUT /scopes/{scopeName}/streams/{streamName}/state¶

Description¶

Updates the current state of the stream

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Path	streamName required	Stream name	string
Body	UpdateStreamStateRequest required	The state info to be updated	StreamState

Responses¶

HTTP Code	Description	Schema
200	Successfully updated the stream state	StreamState
404	Scope or stream with given name not found	No Content
500	Internal server error while updating the stream state	No Content

Consumes¶

application/json

Produces¶

application/json

Tags¶

Streams

Example HTTP request¶

Request path¶

/scopes/string/streams/string/state

Request body¶

{
  "streamState" : "string"
}

Example HTTP response¶

Response 200¶

{
  "streamState" : "string"
}

Definitions¶

ReaderGroupProperty¶

Name	Description	Schema
onlineReaderIds optional	Example : `[ "string" ]`	< string > array
readerGroupName optional	Example : `"string"`	string
scopeName optional	Example : `"string"`	string
streamList optional	Example : `[ "string" ]`	< string > array

ReaderGroupsList¶

Name	Description	Schema
readerGroups optional	Example : `[ "object" ]`	< readerGroups > array

readerGroups

Name	Description	Schema
readerGroupName optional	Example : `"string"`	string

RetentionConfig¶

Name	Description	Schema
timeBasedRetention optional	Example : `"[timebasedretention](#timebasedretention)"`	TimeBasedRetention
type optional	Indicates if retention is by space or time. Example : `"string"`	enum (LIMITED_DAYS, LIMITED_SIZE_MB)
value optional	Example : `0`	integer (int64)

ScaleMetadata¶

Name	Description	Schema
merges optional	Example : `0`	integer (int64)
segmentList optional	Example : `[ "[segment](#segment)" ]`	< Segment > array
splits optional	Example : `0`	integer (int64)
timestamp optional	Example : `0`	integer (int64)

ScalingConfig¶

Name	Description	Schema
minSegments optional	Example : `0`	integer (int32)
scaleFactor optional	Example : `0`	integer (int32)
targetRate optional	Example : `0`	integer (int32)
type optional	Example : `"string"`	enum (FIXED_NUM_SEGMENTS, BY_RATE_IN_KBYTES_PER_SEC, BY_RATE_IN_EVENTS_PER_SEC)

ScalingEventList¶

Name	Description	Schema
scalingEvents optional	Example : `[ "[scalemetadata](#scalemetadata)" ]`	< ScaleMetadata > array

ScopeProperty¶

Name	Description	Schema
scopeName optional	Example : `"string"`	string

ScopesList¶

Name	Description	Schema
scopes optional	Example : `[ "[scopeproperty](#scopeproperty)" ]`	< ScopeProperty > array

Segment¶

Name	Description	Schema
keyEnd optional	Example : `0`	integer (double)
keyStart optional	Example : `0`	integer (double)
number optional	Example : `0`	integer (int32)
startTime optional	Example : `0`	integer (int64)

StreamProperty¶

Name	Description	Schema
retentionPolicy optional	Example : `"[retentionconfig](#retentionconfig)"`	RetentionConfig
scalingPolicy optional	Example : `"[scalingconfig](#scalingconfig)"`	ScalingConfig
scopeName optional	Example : `"string"`	string
streamName optional	Example : `"string"`	string

StreamState¶

Name	Description	Schema
streamState optional	Example : `"string"`	enum (SEALED)

StreamsList¶

Name	Description	Schema
streams optional	Example : `[ "[streamproperty](#streamproperty)" ]`	< StreamProperty > array

TimeBasedRetention¶

Name	Description	Schema
days optional	Example : `0`	integer (int64)
hours optional	Example : `0`	integer (int64)
minutes optional	Example : `0`	integer (int64)