Introduction
The Streaming Analytics API allows applications to programmatically use IBM® Streams in the cloud, providing the ability to start, stop, and manage Streaming Analytics instances, submit Streams jobs, etc. in a manner that is cloud friendly and scalable. All Streaming Analytics instances are highly available.
Authentication
Authentication and Authorization to the Streaming Analytics REST API are enforced by using an IAM access token. The token is used to determine the identity and access roles for using the API.
Use of the Streaming Analytics REST API is done by
adding a valid IAM access token to the HTTP Authorization request header.
Example: -H "Authorization: Bearer ${access_token}"
.
For more information, see
Generating an IBM Cloud IAM token by using an API key.
Methods
Get instance information
Retrieves properties, state, and status information about a Streaming Analytics instance.
GET /streaming_analytics/{instance_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Path Parameters
GUID of the Streaming Analytics instance to perform the operation upon
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether the Streaming Analytics instance will be stopped when idle for an extended period of time.
Component Resource Name of the Streaming Analytics instance.
Example:
crn:v1:bluemix:public:streaming-analytics:us-south:a/7752db6e-5cb6-4e6f-89fb-d1f41a64e0ed:a0629351-bcae-42ea-b76a-71505559cda1::
A URL to the documentation for the service.
Example:
https://www.console.bluemix.net/docs/services/StreamingAnalytics/index.html
Example:
true
Streaming Analytics instance GUID.
Example:
a0629351-bcae-42ea-b76a-71505559cda1
Number of jobs on this Streaming Analytics instance.
Example:
5
URL to retrieve jobs for this Streaming Analytics instance.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs
Indicates the maximum number of application nodes allowed in this Streaming Analytics instance. This is a practical limit based upon the size of the environment, and it can be changed if larger instances are required.
Example:
10
Indicates the minimum number of application nodes allowed in this Streaming Analytics instance.
Example:
1
The Streaming Analytics service plan selected for this Streaming Analytics instance.
Example:
entry-container-monthly
Indicates the capability of the of the user. Possible values are:
- Manager: Indicates that the user can stop and modify the instance and instance properties.
- Writer: Indicates the user can start the instance, submit jobs, and cancel jobs, but cannot stop or modify the instance or instance properties.
Example:
Manager
URL to retrieve information on this Streaming Analytics instance.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1
The number of dedicated nodes requested to be assigned to this Streaming Analytics instance.
Example:
4
State of the Streaming Analytics instance.
Possible values: [
STARTED
,STARTING
,STOPPED
,STOPPING
]Example:
STARTED
Status of the Streams instance.
Possible values: [
failed
,partially_failed
,partially_running
,running
,starting
,stopping
,stopped
,unknown
]Example:
running
URL to access the IBM Streams web console
Example:
https://streams.host.domain:port/streams/domain/console
URL to access the IBM Streams instance through IBM Streams product REST API
Example:
https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1
Status Code
Successfully retrieved information about your instance.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "auto_stop": true, "crn": "crn:v1:bluemix:public:streaming-analytics:us-south:a/7752db6e-5cb6-4e6f-89fb-d1f41a64e0ed:a0629351-bcae-42ea-b76a-71505559cda1::", "documentation": "https://www.console.bluemix.net/docs/services/StreamingAnalytics/index.html", "enabled": true, "id": "a0629351-bcae-42ea-b76a-71505559cda1", "job_count": 5, "jobs": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs", "maximum": 10, "minimum": 1, "plan": "entry-container-monthly", "role": "Manager", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1", "size": 4, "state": "STARTED", "status": "running", "streams_console": "https://streams.host.domain:port/streams/domain/console", "streams_self": "https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1" }
Update instance
Sets writable instance properties to start a stopped instance, stop a started instance, and manage capacity or behavior.
PATCH /streaming_analytics/{instance_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,multipart/form-data
,application/octet-stream
,application/x-compressed
,application/x-tar
,application/zip
]Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
Streaming Analytics instance to update.
Indicates whether the Streaming Analytics instance will be stopped when idle for an extended period of time. Subscription and monthly plans do not support setting the auto_stop value.
Example:
true
The new number of dedicated nodes requested to be assigned to this Streaming Analytics instance. The value must be between the instance minimum and maximum values.
Example:
4
The new state of the Streaming Analytics instance.
Allowable values: [
STARTED
,STOPPED
]Example:
STARTED
curl --request PATCH --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}' --header 'authorization: Bearer <token>' --header 'content-type: application/json' --data '{"auto_stop":true,"size":4,"state":"STARTED"}'
var http = require("https"); var options = { "method": "PATCH", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}", "headers": { "authorization": "Bearer <token>", "content-type": "application/json" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.write(JSON.stringify({auto_stop: true, size: 4, state: 'STARTED'}) req.end();
Response
Indicates whether the Streaming Analytics instance will be stopped when idle for an extended period of time.
Component Resource Name of the Streaming Analytics instance.
Example:
crn:v1:bluemix:public:streaming-analytics:us-south:a/7752db6e-5cb6-4e6f-89fb-d1f41a64e0ed:a0629351-bcae-42ea-b76a-71505559cda1::
A URL to the documentation for the service.
Example:
https://www.console.bluemix.net/docs/services/StreamingAnalytics/index.html
Example:
true
Streaming Analytics instance GUID.
Example:
a0629351-bcae-42ea-b76a-71505559cda1
Number of jobs on this Streaming Analytics instance.
Example:
5
URL to retrieve jobs for this Streaming Analytics instance.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs
Indicates the maximum number of application nodes allowed in this Streaming Analytics instance. This is a practical limit based upon the size of the environment, and it can be changed if larger instances are required.
Example:
10
Indicates the minimum number of application nodes allowed in this Streaming Analytics instance.
Example:
1
The Streaming Analytics service plan selected for this Streaming Analytics instance.
Example:
entry-container-monthly
Indicates the capability of the of the user. Possible values are:
- Manager: Indicates that the user can stop and modify the instance and instance properties.
- Writer: Indicates the user can start the instance, submit jobs, and cancel jobs, but cannot stop or modify the instance or instance properties.
Example:
Manager
URL to retrieve information on this Streaming Analytics instance.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1
The number of dedicated nodes requested to be assigned to this Streaming Analytics instance.
Example:
4
State of the Streaming Analytics instance.
Possible values: [
STARTED
,STARTING
,STOPPED
,STOPPING
]Example:
STARTED
Status of the Streams instance.
Possible values: [
failed
,partially_failed
,partially_running
,running
,starting
,stopping
,stopped
,unknown
]Example:
running
URL to access the IBM Streams web console
Example:
https://streams.host.domain:port/streams/domain/console
URL to access the IBM Streams instance through IBM Streams product REST API
Example:
https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1
Status Code
Successfuly updated the instance.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4008E The number of nodes for selected service plan must be from lower bound to upper bound.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "auto_stop": true, "crn": "crn:v1:bluemix:public:streaming-analytics:us-south:a/7752db6e-5cb6-4e6f-89fb-d1f41a64e0ed:a0629351-bcae-42ea-b76a-71505559cda1::", "documentation": "https://www.console.bluemix.net/docs/services/StreamingAnalytics/index.html", "enabled": true, "id": "a0629351-bcae-42ea-b76a-71505559cda1", "job_count": 5, "jobs": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs", "maximum": 10, "minimum": 1, "plan": "entry-container-monthly", "role": "Manager", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1", "size": 4, "state": "STARTED", "status": "running", "streams_console": "https://streams.host.domain:port/streams/domain/console", "streams_self": "https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1" }
Get instance properties
Retrieves information about properties of the Streaming Analytics instance.
GET /streaming_analytics/{instance_id}/properties
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/properties' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/properties/", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Number of properties for the the Streaming Analytics instance.
Example:
1
Information about each instance property.
Status Code
Successfully retrieved instance properties.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "count": 1, "resources": [ { "assignable": true, "default": "error", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" } ] }
Get instance property
Retrieves information about a property of the Streaming Analytics instance.
GET /streaming_analytics/{instance_id}/properties/{property_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
ID of the property of the Streaming Analytics instance. Use the
GET /properties
operation to see a list of possible values for theproperty_id
parameter.
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/properties/{property_id}' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/properties/{property_id}", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
The identifier of the instance property.
Example:
hc.pecTraceLevel
Indicates whether you must restart the instance for a change to take effect.
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
info
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
debug
The pending value for this property that will take effect when the instance is restarted. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
Status Code
Successfully displayed instance property information.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "debug", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" }
Update instance property
Changes the value of a property of the instance.
PATCH /streaming_analytics/{instance_id}/properties/{property_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]Allowable values: [
application/json
,multipart/form-data
,application/octet-stream
,application/x-compressed
,application/x-tar
,application/zip
]
Path Parameters
GUID of the instance to perform the operation.
ID of the property to perform the operation. Use the
GET /properties
operation to see a list of possible values for theproperty_id
parameter.
Query Parameters
Specifies the new value for the instace property.
curl --request PATCH --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/properties/{property_id}?value=string' --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "PATCH", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/properties/{property_id}?value=string", "headers": { "authorization": "Bearer <token>", } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
The identifier of the instance property.
Example:
hc.pecTraceLevel
Indicates whether you must restart the instance for a change to take effect.
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
info
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
debug
The pending value for this property that will take effect when the instance is restarted. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
Status Code
The instance property was successfully updated.
The instance property was accepted. The new value is pending until the next time the instance is started.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "debug", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" }
{ "assignable": true, "default": "debug", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" }
Delete instance property
Deletes the value of a property of the Streaming Analytics instance, resetting the property to its default value.
DELETE /streaming_analytics/{instance_id}/properties/{property_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
ID of the Streaming Analytics instance property to perform the operation. Use the
GET /properties
operation to see a list of possible values for theproperty_id
parameter.
curl --request DELETE --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/properties/{property_id}' --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "DELETE", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/properties/{property_id}", "headers": { "authorization": "Bearer <token>", } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
The identifier of the instance property.
Example:
hc.pecTraceLevel
Indicates whether you must restart the instance for a change to take effect.
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
info
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
debug
The pending value for this property that will take effect when the instance is restarted. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
debug
Status Code
The instance property was successfully deleted.
The instance property variable was deleted. The new value is pending until the next time the instance is started.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "debug", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" }
{ "assignable": true, "default": "debug", "enum": [ "debug" ], "id": "hc.pecTraceLevel", "pending_value": "debug", "requires_restart": false, "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/properties/hc.pecTraceLevel", "value": "info" }
Get jobs
Retrieves information about all jobs on the instance.
GET /streaming_analytics/{instance_id}/jobs
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/jobs' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/jobs", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Number of visible jobs currently active in the Streaming Analytics instance.
Example:
1
Information about each job currently visible in the Streams instance.
Status Code
Successfully retrieved all jobs on the instance.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "count": 1, "resources": [ { "application": "sample::Counter", "health": "healthy", "id": 2, "name": "sample::Counter_0", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs/sample::Counter_0", "streams_self": "https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1/jobs/2" } ] }
Submit job
Submits a Streams application to this Streaming Analytics instance. This operation consumes multipart/form-data. One part of the multipart/form-data contains JSON providing job submission information. The job submission JSON request must follow one of the following schemas:
- Basic: optional values for jobName, jobGroup, submissionParameters and configurationSettings.
- Complex: an IBM Streams job configuration overlay JSON file that contains name-value pairs for the submission-time configuration parameters. The configuration overlay file can be manually constructed or generated by the IBM Streams product.
The other part of the multipart/form-data contains the Streams application bundle. Swagger does not support the specification of a (JSON) object type within form data. Consequently, the API documentation below does not directly contain an example of the Basic job submission schema. You can use the following CURL command to exercise this API, by substituting your own values for Bearer Token, instance GUID and .sab file name.
curl -X POST --tlsv1.2 -k -H "Authorization: Bearer <token>" -H "Accept: application/json" -F "bundle_file=@<sab-file-name>.sab;type=application/octet-stream" -F 'job_options={};type=application/json' https://host:port/v2/streaming_analtyics/<instance_id>/jobs
Note: Any .sab file (Streams Application Bundle) that you submit to this environment must be compatible with a RHEL 7.x environment (or CentOS equivalent). In addition, the development environment must be a compatible Streams 4.x environment (Streams 4.2.4 or earlier.)
POST /streaming_analytics/{instance_id}/jobs
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Content-Type: multipart/form-data must be specified
Path Parameters
GUID of the Streaming Analytics instance to perform the operation
Form Parameters
A JSON object containing attributes and parameters for the job submission, that includes optional values for jobName, jobGroup, submissionParameters and configurationSettings (as described by the IBM Streams product documentation.)
The Streaming Analytics application bundle (.sab) file to submit.
curl --request POST --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/jobs' --header 'accept: application/json' --header 'authorization: Bearer <token>' --header 'content-type: multipart/form-data' --data 'bundle_file=filename.txt&job_options=string'
var http = require("https"); var options = { "method": "POST", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/jobs", "headers": { "authorization": "Bearer <token>", "accept": "application/json", "content-type": "multipart/form-data" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.write(JSON.stringify({bundle_file: 'filename.txt', job_options: 'string'}) req.end();
Response
The name of the Streams application that the job is running
Example:
sample::Counter
The health status of the Streams job.
Possible values: [
healthy
,partiallyHealthy
,partiallyUnhealthy
,unhealthy
,unknown
]Example:
healthy
The numeric job ID of the Streams job
Example:
2
The name assigned to the Streams job
Example:
sample::Counter_0
URL to retrieve information on this Streams job.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs/sample::Counter_0
URL to access the IBM Streams job through IBM Streams product REST API
Example:
https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1/jobs/2
Status Code
The job was successfully created.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4005E An entity with the specified identification was not found.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "application": "sample::Counter", "health": "healthy", "id": 2, "name": "sample::Counter_0", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs/sample::Counter_0", "streams_self": "https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1/jobs/2" }
Get job
Retrieves information on a Streams job. The {job_id} is assumed to be the Streams job name, unless the value is numeric. If the value is numeric, the {job_id} is assumed to be the Streams job ID. Consequently, ambiguity can result if numerics are used to name Streams jobs.
GET /streaming_analytics/{instance_id}/jobs/{job_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation
The job name or the numeric job ID of the Streams job to retrieve. The {job_id} is assumed to be the Stream job name, unless the value is numeric. If the value is numeric, the {job_id} is assumed to be the Streams job ID.
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics{instance_id}/jobs/{job_id}' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics{instance_id}/jobs/{job_id}", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
The name of the Streams application that the job is running
Example:
sample::Counter
The health status of the Streams job.
Possible values: [
healthy
,partiallyHealthy
,partiallyUnhealthy
,unhealthy
,unknown
]Example:
healthy
The numeric job ID of the Streams job
Example:
2
The name assigned to the Streams job
Example:
sample::Counter_0
URL to retrieve information on this Streams job.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs/sample::Counter_0
URL to access the IBM Streams job through IBM Streams product REST API
Example:
https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1/jobs/2
Status Code
Successfully retrieved information about the job.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4005E An entity with the specified identification was not found.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "application": "sample::Counter", "health": "healthy", "id": 2, "name": "sample::Counter_0", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/jobs/sample::Counter_0", "streams_self": "https://streams.host.domain:port/rest/instances/a0629351-bcae-42ea-b76a-71505559cda1/jobs/2" }
Cancel job
Cancels a Streams job. The {job_id} is assumed to be the Stream job name, unless the value is numeric. If the value is numeric, the {job_id} is assumed to be the Streams job ID. Consequently, ambiguity can result if numerics are used to name Streams jobs.
DELETE /streaming_analytics/{instance_id}/jobs/{job_id}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation upon
The job name or the numeric job ID of the Streams job to cancel. The {job_id} is assumed to be the Stream job name, unless the value is numeric. If the value is numeric, the {job_id} is assumed to be the Streams job ID.
curl --request DELETE --url 'https://{rest_url}/v2/streaming_analytics{instance_id}/jobs/{job_id}' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "DELETE", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics{instance_id}/jobs/{job_id}", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Status Code
Successfully deleted the job.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4005E An entity with the specified identification was not found.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "": "object" }
Get Application Environment Variables
Retrieves information about environment variables of the Streaming Analytics instance.
GET /streaming_analytics/{instance_id}/app_env_vars
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/app_env_vars' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/app_env_vars/", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Number of properties for the the Streaming Analytics instance.
Example:
1
Information about each instance property.
Status Code
Successfully retrieved environment variables.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "count": 1, "resources": [ { "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" } ] }
Get environment variable.
Retrieves information about an environment variable of the Streaming Analytics instance.
GET /streaming_analytics/{instance_id}/app_env_vars/{variable_name}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
Name of the variable of the Streaming Analytics instance. Use the
GET /app_env_vars
operation to see a list of possible values for thevariable_name
parameter.
curl --request GET --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}' \ - | --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "GET", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}", "headers": { "authorization": "Bearer <token>" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the enviornment variable. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
/usr/IBM/anaconda3
The identifier of the enviornment variable.
Example:
PYTHONHOME
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3.6
Status Code
Successfully displayed instance environment variable information.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" }
Update environment variable
Changes the value of an environment variable of the instance.
PATCH /streaming_analytics/{instance_id}/app_env_vars/{variable_name}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]Allowable values: [
application/json
,multipart/form-data
,application/octet-stream
,application/x-compressed
,application/x-tar
,application/zip
]
Path Parameters
GUID of the instance to perform the operation.
Name of the variable to perform the operation. Use the
GET /app_env_vars
operation to see a list of possible values for thevariable_name
parameter.
Query Parameters
Specifies the new value for the instace property.
curl --request PATCH --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}?value=string' --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "PATCH", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}?value=string", "headers": { "authorization": "Bearer <token>", } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the enviornment variable. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
/usr/IBM/anaconda3
The identifier of the enviornment variable.
Example:
PYTHONHOME
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3.6
Status Code
The instance environment variable was successfully updated.
The instance environment variable was accepted. The new value is pending until the next time the instance is started.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" }
{ "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" }
Delete environment variable.
Deletes the value of a environment variable of the Streaming Analytics instance, resetting the environment variable to its default value..
DELETE /streaming_analytics/{instance_id}/app_env_vars/{variable_name}
Request
Custom Headers
Identity Access Management (IAM) bearer token.
Allowable values: [
application/json
,application/octet-stream
]
Path Parameters
GUID of the Streaming Analytics instance to perform the operation.
ID of the Streaming Analytics instance environment variable to perform the operation. Use the
GET /app_env_vars
operation to see a list of possible values for thevariable_name
parameter.
curl --request DELETE --url 'https://{rest_url}/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}' --header 'authorization: Bearer <token>'
var http = require("https"); var options = { "method": "DELETE", "hostname": "{rest_url}", "port": null, "path": "/v2/streaming_analytics/{instance_id}/app_env_vars/{variable_name}", "headers": { "authorization": "Bearer <token>", } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString ()); }); }); req.end();
Response
Indicates whether you can change the value of the instance property.
Example:
true
The dafault value for the enviornment variable. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3
An enumerated list of allowed values for the property. Use this optional value is only for properties with a restricted list of allowed values.
Example:
/usr/IBM/anaconda3
The identifier of the enviornment variable.
Example:
PYTHONHOME
URL pointing to this instance property.
Example:
https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME
The current value of the instance property. The data type can be "STRING", "INTEGER", or "BOOLEAN" depending on the data type of the property.
Example:
/usr/IBM/anaconda3.6
Status Code
The instance environment variable was successfully deleted.
The instance environment variable was deleted. The new value is pending until the next time the instance is started.
- CDISB4003E Service instance with the specified instance identification was not found.
- CDISB4001E One or more of the operation inputs are not valid for the service or not valid for the current state of the service instance.
- CDISB4002E One or more required service inputs were not provided.
- CDISB4009E Specified instance property is not supported by this service.
CDISB4010E Requested file or operation is not accessible with current authorization.
CDISB4030E Requested file or operation is not accessible.
CDISB4040E Requested file or operation was not found.
CDISB4090E Request operation could not be completed. The operation is not valid for the service or not valid for the current state of the service instance.
CDISB4100E Service instance with the specified instance identification is gone.
An error occurred.
{ "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" }
{ "assignable": true, "default": "/usr/IBM/anaconda3", "enum": [ "/usr/IBM/anaconda3", "/usr/IBM/anaconda3.6", "/usr/IBM/anaconda3.5" ], "id": "PYTHONHOME", "self": "https://host.domain:port/v2/streaming_analytics/a0629351-bcae-42ea-b76a-71505559cda1/app_env_vars/PYTHONHOME", "value": "/usr/IBM/anaconda3" }