Skip to content

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)