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. The Streaming Analytics v2 API is only supported on service instances created with one of the new container-based service plans. The v1 API is only supported on existing Streaming Analytics instances and any new instances you create with v1 service plans. All Streaming Analytics instances are highly available.

Error handling

The Streaming Analytics service API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Security

Every request must include the Authorization HTTP header with the value of the Identity Access Management (IAM) bearer token <access_token>. For more information, see Getting an IBM Cloud IAM token by using an API key.

If you are using the v1 service plans, check out the Streaming Analytics v1 API. You can also try the Geospatial Analytics API to leverage real-time geospatial analytics to track when devices enter, leave or hang out in defined regions.

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.

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

Path Parameters

  • GUID of the Streaming Analytics instance to perform the operation upon

Example requests
Response

Status Code

  • Successfully retrieved information about your instance.

  • The request was invalid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • Not Found

  • Unavailable

  • Gone

  • Error

Example responses

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.

Example requests
Response

Status Code

  • Successfuly updated the instance.

  • The request was invalid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The requested instance was not found.

  • The requested instance is not available.

  • The requested instance is not available.

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

Path Parameters

  • GUID of the Streaming Analytics instance to perform the operation.

Example requests
Response

Status Code

  • Successfully retrieved instance properties.

  • The request was not valid.

  • Unauthorized

  • You must have the right permissions to perform this operation.

  • Not Found

  • The instance is not available.

  • Gone

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

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 the property_id parameter.

Example requests
Response

Status Code

  • Successfully displayed instance property information.

  • The request was not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The instance property was not found.

  • The instance property is not available.

  • Gone

  • An error occurred.

Example responses

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 the property_id parameter.

Query Parameters

  • Specifies the new value for the instace property.

Example requests
Response

Status Code

  • The instance property was successfully updated.

  • The instance property was successfully updated.

  • The request was not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The instance property was not found.

  • The instance property is not available.

  • Gone

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

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 the property_id parameter.

Example requests
Response

Status Code

  • The instance property was successfully deleted.

  • The instance property was successfully deleted.

  • The request is not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The instance property was not found.

  • The instance property is not available.

  • Gone

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

Path Parameters

  • GUID of the Streaming Analytics instance to perform the operation

Example requests
Response

Status Code

  • Successfully retrieved all jobs on the instance.

  • The request is not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • No jobs were found on the instance.

  • The instance is not available.

  • Gone

  • An error occurred.

Example responses

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.

Example requests
Response

Status Code

  • The job was successfully created.

  • The request was invalid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The job was not found.

  • The job is not available.

  • Gone

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

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.

Example requests
Response

Status Code

  • Successfully retrieved information about the job.

  • The request is not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The job was not found.

  • The job is not available.

  • Gone

  • An error occurred.

Example responses

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]

  • Allowable values: [application/json,multipart/form-data,application/octet-stream,application/x-compressed,application/x-tar,application/zip]

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.

Example requests
Response

Status Code

  • Successfully deleted the job.

  • The request was not valid.

  • You must have the right permissions to perform this operation.

  • You must have the right permissions to perform this operation.

  • The job was not found.

  • The job is not available.

  • Gone

  • An error occurred.

Example responses