Skip to content

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