Pravega Controller APIs¶

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¶

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

Paths¶

GET /health¶

Description¶

Return the Health of the Controller service.

Responses¶

HTTP Code	Description	Schema
200	The Health result of the Controller.	HealthResult
500	Internal server error while fetching the Health.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health

Example HTTP response¶

Response 200¶

{
  "name" : "string",
  "status" : { },
  "readiness" : true,
  "liveness" : true,
  "details" : { },
  "children" : {
    "string" : "[healthresult](#healthresult)"
  }
}

GET /health/details¶

Description¶

Fetch the details of the Controller service.

Responses¶

HTTP Code	Description	Schema
200	The list of details.	HealthDetails
500	Internal server error while fetching the health details of the Controller.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/details

Example HTTP response¶

Response 200¶

{ }

GET /health/details/{id}¶

Description¶

Fetch the details of a specific health contributor.

Parameters¶

Type	Name	Description	Schema
Path	id required	The id of an existing health contributor.	string

Responses¶

HTTP Code	Description	Schema
200	The list of details for the health contributor with a given id.	HealthDetails
404	The health details for the contributor with given id was not found.	No Content
500	Internal server error while fetching the health details for a given health contributor.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/details/string

Example HTTP response¶

Response 200¶

{ }

GET /health/liveness¶

Description¶

Fetch the liveness state of the Controller service.

Responses¶

HTTP Code	Description	Schema
200	The alive status.	boolean
500	Internal server error while fetching the liveness state of the Controller.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/liveness

Example HTTP response¶

Response 200¶

true

GET /health/liveness/{id}¶

Description¶

Fetch the liveness state of the specified health contributor.

Parameters¶

Type	Name	Description	Schema
Path	id required	The id of an existing health contributor.	string

Responses¶

HTTP Code	Description	Schema
200	The alive status for the specified health contributor.	boolean
404	The liveness status for the contributor with given id was not found.	No Content
500	Internal server error while fetching the liveness state for a given health contributor.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/liveness/string

Example HTTP response¶

Response 200¶

true

GET /health/readiness¶

Description¶

Fetch the ready state of the Controller service.

Responses¶

HTTP Code	Description	Schema
200	The ready status.	boolean
500	Internal server error while fetching the ready state of the Controller.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/readiness

Example HTTP response¶

Response 200¶

true

GET /health/readiness/{id}¶

Description¶

Fetch the ready state of the health contributor.

Parameters¶

Type	Name	Description	Schema
Path	id required	The id of an existing health contributor.	string

Responses¶

HTTP Code	Description	Schema
200	The readiness status for the health contributor with given id.	boolean
404	The readiness status for the contributor with given id was not found.	No Content
500	Internal server error while fetching the ready state for a given health contributor.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/readiness/string

Example HTTP response¶

Response 200¶

true

GET /health/status¶

Description¶

Fetch the status of the Controller service.

Responses¶

HTTP Code	Description	Schema
200	The health status of the Controller.	HealthStatus
500	Internal server error while fetching the health status of the Controller.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/status

Example HTTP response¶

Response 200¶

{ }

GET /health/status/{id}¶

Description¶

Fetch the status of a specific health contributor.

Parameters¶

Type	Name	Description	Schema
Path	id required	The id of an existing health contributor.	string

Responses¶

HTTP Code	Description	Schema
200	The health status of the Controller.	HealthStatus
404	The health status for the contributor with given id was not found.	No Content
500	Internal server error while fetching the health status of a given health contributor.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/status/string

Example HTTP response¶

Response 200¶

{ }

GET /health/{id}¶

Description¶

Return the Health of a health contributor with a given id.

Parameters¶

Type	Name	Description	Schema
Path	id required	The id of an existing health contributor.	string

Responses¶

HTTP Code	Description	Schema
200	The Health result of the Controller.	HealthResult
404	A health provider for the given id could not be found.	No Content
500	Internal server error while fetching the health for a given contributor.	No Content

Produces¶

application/json

Tags¶

Health

Example HTTP request¶

Request path¶

/health/string

Example HTTP response¶

Response 200¶

{
  "name" : "string",
  "status" : { },
  "readiness" : true,
  "liveness" : true,
  "details" : { },
  "children" : {
    "string" : "[healthresult](#healthresult)"
  }
}

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
rolloverSizeBytes optional	Example : `"[rolloversizebytes](#rolloversizebytes)"`	RolloverSizeBytes
scalingPolicy optional	Example : `"[scalingconfig](#scalingconfig)"`	ScalingConfig
streamName optional	Example : `"string"`	string
streamTags optional	Example : `"[tagslist](#tagslist)"`	TagsList
timestampAggregationTimeout optional	Example : `"[timestampaggregationtimeout](#timestampaggregationtimeout)"`	TimestampAggregationTimeout

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
    },
    "maxValue" : 0,
    "maxTimeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  },
  "streamTags" : { },
  "timestampAggregationTimeout" : { },
  "rolloverSizeBytes" : { }
}

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
    },
    "maxValue" : 0,
    "maxTimeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  },
  "tags" : { }
}

GET /scopes/{scopeName}/streams¶

Description¶

List streams within the given scope

Parameters¶

Type	Name	Description	Schema
Path	scopeName required	Scope name	string
Query	filter_type optional	Filter options	enum (showInternalStreams, tag)
Query	filter_value optional	value to be passed. must match the type passed with it.	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
      },
      "maxValue" : 0,
      "maxTimeBasedRetention" : {
        "days" : 0,
        "hours" : 0,
        "minutes" : 0
      }
    },
    "tags" : { }
  } ]
}

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
    },
    "maxValue" : 0,
    "maxTimeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  },
  "tags" : { }
}

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
rolloverSizeBytes optional	Example : `"[rolloversizebytes](#rolloversizebytes)"`	RolloverSizeBytes
scalingPolicy optional	Example : `"[scalingconfig](#scalingconfig)"`	ScalingConfig
streamTags optional	Example : `"[tagslist](#tagslist)"`	TagsList
timestampAggregationTimeout optional	Example : `"[timestampaggregationtimeout](#timestampaggregationtimeout)"`	TimestampAggregationTimeout

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
    },
    "maxValue" : 0,
    "maxTimeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  },
  "streamTags" : { },
  "timestampAggregationTimeout" : { },
  "rolloverSizeBytes" : { }
}

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
    },
    "maxValue" : 0,
    "maxTimeBasedRetention" : {
      "days" : 0,
      "hours" : 0,
      "minutes" : 0
    }
  },
  "tags" : { }
}

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¶

HealthDetails¶

Type : < string, string > map

HealthResult¶

Name	Description	Schema
children optional	Example : `{<br> "string" : "[healthresult](#healthresult)"<br>}`	< string, HealthResult > map
details optional	Example : `"[healthdetails](#healthdetails)"`	HealthDetails
liveness optional	Example : `true`	boolean
name optional	Example : `"string"`	string
readiness optional	Example : `true`	boolean
status optional	Example : `"[healthstatus](#healthstatus)"`	HealthStatus

HealthStatus¶

Type : enum (UP, STARTING, NEW, UNKNOWN, FAILED, DOWN)

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
maxTimeBasedRetention optional	Example : `"[timebasedretention](#timebasedretention)"`	TimeBasedRetention
maxValue optional	Example : `0`	integer (int64)
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)

RolloverSizeBytes¶

Type : long

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
tags optional	Example : `"[tagslist](#tagslist)"`	TagsList

StreamState¶

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

StreamsList¶

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

TagsList¶

Type : < string > array

TimeBasedRetention¶

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

TimestampAggregationTimeout¶

Type : long