Project: Pravega (App Definition and Development / Streaming & Messaging)
File: restapis.md

<a name="overview"></a> List of admin REST APIs for the Pravega controller service. Version : 0.0.1 License : Apache 2.0 License URL : http://www.apache.org/licenses/LICENSE-2.0 Terms of service : null BasePath : /v1 Schemes : HTTP Health : Health check related APIs ReaderGroups : Reader group related APIs Scopes : Scope related APIs Streams : Stream related APIs <a name="paths"></a> <a name="gethealth"></a> Return the Health of the Controller service. |HTTP Code|Description|Schema| |||| |200|The Health result of the Controller.|| |500|Internal server error while fetching the Health.|No Content| `application/json` Health ``` /health ``` ```json { "name" : "string", "status" : { }, "readiness" : true, "liveness" : true, "details" : { }, "children" : { "string" : "" } } ``` <a name="getdetails"></a> Fetch the details of the Controller service. |HTTP Code|Description|Schema| |||| |200|The list of details.|| |500|Internal server error while fetching the health details of the Controller.|No Content| `application/json` Health ``` /health/details ``` ```json { } ``` <a name="getcontributordetails"></a> Fetch the details of a specific health contributor. |Type|Name|Description|Schema| ||||| |Path|id <br>required|The id of an existing health contributor.|string| |HTTP Code|Description|Schema| |||| |200|The list of details for the health contributor with a given id.|| |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| `application/json` Health ``` /health/details/string ``` ```json { } ``` <a name="getliveness"></a> Fetch the liveness state of the Controller service. |HTTP Code|Description|Schema| |||| |200|The alive status.|boolean| |500|Internal server error while fetching the liveness state of the Controller.|No Content| `application/json` Health ``` /health/liveness ``` ```json true ``` <a name="getcontributorliveness"></a> Fetch the liveness state of the specified health contributor. |Type|Name|Description|Schema| ||||| |Path|id <br>required|The id of an existing health contributor.|string| |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| `application/json` Health ``` /health/liveness/string ``` ```json true ``` <a name="getreadiness"></a> Fetch the ready state of the Controller service. |HTTP Code|Description|Schema| |||| |200|The ready status.|boolean| |500|Internal server error while fetching the ready state of the Controller.|No Content| `application/json` Health ``` /health/readiness ``` ```json true ``` <a name="getcontributorreadiness"></a> Fetch the ready state of the health contributor. |Type|Name|Description|Schema| ||||| |Path|id <br>required|The id of an existing health contributor.|string| |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| `application/json` Health ``` /health/readiness/string ``` ```json true ``` <a name="getstatus"></a> Fetch the status of the Controller service. |HTTP Code|Description|Schema| |||| |200|The health status of the Controller.|| |500|Internal server error while fetching the health status of the Controller.|No Content| `application/json` Health ``` /health/status ``` ```json { } ``` <a name="getcontributorstatus"></a> Fetch the status of a specific health contributor. |Type|Name|Description|Schema| ||||| |Path|id <br>required|The id of an existing health contributor.|string| |HTTP Code|Description|Schema| |||| |200|The health status of the Controller.|| |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| `application/json` Health ``` /health/status/string ``` ```json { } ``` <a name="getcontributorhealth"></a> Return the Health of a health contributor with a given id. |Type|Name|Description|Schema| ||||| |Path|id <br>required|The id of an existing health

|HTTP Code|Description|Schema| |||| |200|The Health result of the Controller.|| |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

Content| `application/json` Health ``` /health/string ``` ```json { "name" : "string", "status" : { }, "readiness" : true, "liveness" : true, "details" : { }, "children" : { "string" : "" } } ``` <a name="createscope"></a> Create a new scope |Type|Name|Description|Schema| ||||| |Body|CreateScopeRequest <br>required|The scope configuration|| <a name="createscope-createscoperequest"></a> CreateScopeRequest |Name|Description|Schema| |||| |scopeName <br>optional|Example : `"string"`|string| |HTTP Code|Description|Schema| |||| |201|Successfully created the scope|| |409|Scope with the given name already exists|No Content| |500|Internal server error while creating a scope|No Content| `application/json` `application/json` Scopes ``` /scopes ``` ```json { "scopeName" : "string" } ``` ```json { "scopeName" : "string" } ``` <a name="listscopes"></a> List all available scopes in Pravega |HTTP Code|Description|Schema| |||| |200|List of currently available scopes|| |500|Internal server error while fetching list of scopes|No Content| `application/json` Scopes ``` /scopes ``` ```json { "scopes" : [ { "scopeName" : "string" } ] } ``` <a name="getscope"></a> Retrieve details of an existing scope |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |HTTP Code|Description|Schema| |||| |200|Successfully retrieved the scope details|| |404|Scope with the given name not found|No Content| |500|Internal server error while fetching scope details|No Content| `application/json` Scopes ``` /scopes/string ``` ```json { "scopeName" : "string" } ``` <a name="deletescope"></a> Delete a scope |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |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| Scopes ``` /scopes/string ``` <a name="listreadergroups"></a> List reader groups within the given scope |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |HTTP Code|Description|Schema| |||| |200|List of all reader groups configured for the given scope|| |404|Scope not found|No Content| |500|Internal server error while fetching the list of reader groups for the given scope|No Content| `application/json` ReaderGroups ``` /scopes/string/readergroups ``` ```json { "readerGroups" : [ "object" ] } ``` <a name="getreadergroup"></a> Fetch the properties of an existing reader group |Type|Name|Description|Schema| ||||| |Path|readerGroupName <br>required|Reader group name|string| |Path|scopeName <br>required|Scope name|string| |HTTP Code|Description|Schema| |||| |200|Found reader group properties|| |404|Scope or reader group with given name not found|No Content| |500|Internal server error while fetching reader group details|No Content| `application/json` ReaderGroups ``` /scopes/string/readergroups/string ``` ```json { "scopeName" : "string", "readerGroupName" : "string", "streamList" : [ "string" ], "onlineReaderIds" : [ "string" ] } ``` <a name="deletereadergroup"></a> Delete a reader group |Type|Name|Description|Schema| ||||| |Path|readerGroupName <br>required|Reader group name|string| |Path|scopeName <br>required|Scope name|string| |HTTP Code|Description|Schema| |||| |204|Successfully deleted the reader group|No Content| |404|Reader group with given name not found|No Content| |500|Internal server error while deleting a reader group|No Content| ReaderGroups ``` /scopes/string/readergroups/string ``` <a name="createstream"></a> Create a new stream |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Body|CreateStreamRequest <br>required|The stream configuration|| <a name="createstream-createstreamrequest"></a> CreateStreamRequest |Name|Description|Schema| |||| |retentionPolicy <br>optional|Example : `""`|| |rolloverSizeBytes <br>optional|Example : `""`|| |scalingPolicy <br>optional|Example : `""`|| |streamName <br>optional|Example : `"string"`|string| |streamTags <br>optional|Example : `""`|| |timestampAggregationTimeout <br>optional|Example : `""`|| |HTTP Code|Description|Schema| |||| |201|Successfully created the stream with the given configuration|| |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| `application/json` `application/json` Streams ``` /scopes/string/streams ``` ```json { "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" : { } } ``` ```json { "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" : { } } ``` <a name="liststreams"></a> List streams within the given scope |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Query|filter_type <br>optional|Filter options|enum (showInternalStreams, tag)| |Query|filter_value <br>optional|value to be passed. must match the type passed with

|HTTP Code|Description|Schema| |||| |200|List of all streams configured for the given scope|| |404|Scope not found|No Content| |500|Internal server error while fetching the list of streams for the given scope|No Content| `application/json` Streams ``` /scopes/string/streams ``` ```json { "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" : { } } ] } ``` <a name="getstream"></a> Fetch the properties of an existing stream |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Path|streamName <br>required|Stream name|string| |HTTP Code|Description|Schema| |||| |200|Found stream properties|| |404|Scope or stream with given name not found|No Content| |500|Internal server error while fetching stream details|No Content| `application/json` Streams ``` /scopes/string/streams/string ``` ```json { "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" : { } } ``` <a name="updatestream"></a> Update configuration of an existing stream |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Path|streamName <br>required|Stream name|string| |Body|UpdateStreamRequest <br>required|The new stream configuration|| <a name="updatestream-updatestreamrequest"></a> UpdateStreamRequest |Name|Description|Schema| |||| |retentionPolicy <br>optional|Example : `""`|| |rolloverSizeBytes <br>optional|Example : `""`|| |scalingPolicy <br>optional|Example : `""`|| |streamTags <br>optional|Example : `""`|| |timestampAggregationTimeout <br>optional|Example : `""`|| |HTTP Code|Description|Schema| |||| |200|Successfully updated the stream configuration|| |404|Scope or stream with given name not found|No Content| |500|Internal server error while updating the stream|No Content| `application/json` `application/json` Streams ``` /scopes/string/streams/string ``` ```json { "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" : { } } ``` ```json { "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" : { } } ``` <a name="deletestream"></a> Delete a stream |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Path|streamName <br>required|Stream name|string| |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| Streams ``` /scopes/string/streams/string ``` <a name="getscalingevents"></a> Get scaling events for a given datetime period. |Type|Name|Description|Schema| ||||| |Path|scopeName <br>required|Scope name|string| |Path|streamName <br>required|Stream name|string| |Query|from <br>required|Parameter to display scaling events from that particular datetime. Input should be milliseconds from Jan 1 1970.|integer (int64)| |Query|to <br>required|Parameter to display scaling events to that particular datetime. Input should be milliseconds from Jan 1 1970.|integer (int64)| |HTTP Code|Description|Schema| |||| |200|Successfully fetched list of scaling events.|| |404|Scope/Stream not found.|No Content| |500|Internal Server error while fetching scaling events.|No Content| `application/json` Streams ``` /scopes/string/streams/string/scaling-events?from=0&to=0 ``` ```json { "scalingEvents" : [ { "timestamp" : 0, "segmentList" : [ { "number" : 0, "startTime" : 0, "keyStart" : 0, "keyEnd" : 0 } ], "splits" : 0, "merges"