Introduction

IBM® Streaming Analytics for IBM Cloud is powered by IBM® Streams, an advanced analytic platform that you can use to ingest, analyze, and correlate information as it arrives from different types of data sources in real time. When you create an instance of the Streaming Analytics service, you get your own instance of IBM® Streams running in IBM Cloud™, ready to run your IBM® Streams applications.

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.

If you are using the v2 service plans, check out the Streaming Analytics v2 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 information about one or more jobs

Retrieves information about all jobs that are running on a service instance.

To retrieve information for all jobs in the instance, do not specify the job_id or the job_name parameter. To retrieve information for a single job, specify the job_id or the job_name parameter.

GET /jax-rs/jobs/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Query Parameters

  • Use this parameter to get the information of a specific job.The numeric job ID assigned to the job. You can specify the job_id parameter or the job_name parameter.

  • Use this parameter to get the information of a specific job. The name that is assigned to the IBM Streams job. You can specify the job_id parameter or the job_name parameter.

Response

Status Code

  • Successful response

Example responses

Upload and submit job

Uploads and submits a job to the service instance.

You must enter the following information in the POST request in a MULTIPART_FORM_DATA body:

  • IBM Streams bundle (.sab) file passed as "application/octet-stream"
  • A JSON object passed as "application/json" that contains the submission parameters and configuration settings or a JSON file that contains the job configuration overlays.

This API documentation is specified in Swagger, and the Swagger specification does not support the combination of features that are used by this operation.

The JSON object that contains configuration settings is described in the Request example section. To get details and syntax examples of the job configuration overlays JSON file, see the IBM Streams product documentation.

POST /jax-rs/jobs/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service Bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Query Parameters

  • The name of the bundle file (*.sab).

  • A job configuration overlay is a JSON file that contains name-value pairs for the submission-time configuration parameters that you want to use. You can manually create a job configuration overlay file.

  • A JSON object containing attributes and parameters for the job submission.

The name to be assigned to job.

Response

Status Code

  • Successful response

Example responses

Cancel and delete job

Cancels and deletes the selected job from the service instance.

DELETE /jax-rs/jobs/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID establised on the service provision sequence. You can find the parameter value in the service credentials.

Query Parameters

  • The job ID assigned to the running job. You must specify either the {jobId} parameter or the {jobName} parameter.

  • The name that is assigned to the job. You must specify either the {jobId} parameter or the {jobName} parameter.

Response

Status Code

  • Successful response

Example responses

List all instance resources

Retrieves information about the dedicated application nodes (IBM Streams resources) that are assigned to a service instance.

GET /jax-rs/resources/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Response

Status Code

Example responses

Retrieve instance size

Retrieves the size, in number of dedicated application nodes (IBM Streams resources), of the service instance. By default, the service instance is configured with two dedicated application nodes.

GET /jax-rs/streams/size/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Response

Status Code

  • OK

Example responses

Edit instance size

Sets the size, in number of dedicated application nodes, of your Streaming Analytics service instance. If the instance is running, you are only allowed to increase the size. If the instance is stopped, you can increase or decrease its size.

PUT /jax-rs/streams/size/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Defines the number of application nodes in the service instance

Response

Status Code

  • Successful response

Example responses

Start a service instance

Starts a stopped service instance.

PUT /jax-rs/streams/start/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Query Parameters

  • Enter an empty JSON object

Response

Status Code

  • Successful response

Example responses

Retrieve instance status

Retrieves the state and status information about a service instance.

GET /jax-rs/streams/status/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

Response

Status Code

  • Successful response

Example responses

Stop instance

Stops a running service instance.

PUT /jax-rs/streams/stop/service_instances/{instanceId}/service_bindings/{bindingId}
Request

Path Parameters

  • The bind ID established on the service bind sequence. You can find the parameter value in the service credentials.

  • The service instance ID established on the service provision sequence. You can find the parameter value in the service credentials.

Query Parameters

  • Enter an empty JSON object.

Response

Status Code

  • Successful response

Example responses