streamsx.rest

REST API bindings for IBM® Streams & Streaming Analytics service.

Streams REST API

The Streams REST API provides programmatic access to configuration and status information for IBM Streams objects such as domains, instances, and jobs.

IBM Cloud Pak for Data (Streams 5)

Integrated configuration within project

of_service() is the entry point to using the Streams REST API bindings, returning an Instance. The configuration required to connect is obtained from ipcd_util.get_service_details passing in the IBM Streams service instance name.

Integrated & standalone configurations

of_endpoint() is the entry point to using the Streams REST API bindings, returning an Instance.

IBM Streams On-premises (4.2, 4.3)

StreamsConnection is the entry point to using the Streams REST API bindings. Through its functions and the returned objects status information can be obtained for items such as instances and jobs.

Streaming Analytics REST API

You can use the Streaming Analytics REST API to manage your service instance and the IBM Streams jobs that are running on the instance. The Streaming Analytics REST API is accessible from IBM Cloud applications that are bound to your service instance or from an application outside of IBM Cloud that is configured with the service instance VCAP information.

StreamingAnalyticsConnection is the entry point to using the Streaming Analytics REST API. The function get_streaming_analytics() returns a StreamingAnalyticsService instance which is the wrapper around the Streaming Analytics REST API. This API allows functions such as start and stop the service instance.

In addition StreamingAnalyticsConnection extends from StreamsConnection and thus provides access to the Streams REST API for the service instance.

See also

IBM Streams REST API overview

Reference documentation for the Streams REST API.

Streaming Analytics REST API

Reference documentation for the Streaming Analytics service REST API.

Module contents

Classes

StreamingAnalyticsConnection

Creates a connection to a running Streaming Analytics service and exposes methods to retrieve the state of the service and its instance.

StreamsConnection

Creates a connection to a running distributed IBM Streams instance and exposes methods to retrieve the state of that instance.

class streamsx.rest.StreamsConnection(username=None, password=None, resource_url=None, auth=None)

Bases: streamsx.rest._AbstractStreamsConnection

Creates a connection to a running distributed IBM Streams instance and exposes methods to retrieve the state of that instance.

Streams maintains information regarding the state of its resources. For example, these resources could include the currently running Jobs, Views, PEs, Operators, and Domains. The StreamsConnection provides methods to retrieve that information.

Parameters
  • username (str) – Username of an authorized Streams user. If None, the username is taken from the STREAMS_USERNAME environment variable. If the STREAMS_USERNAME environment variable is not set, the default streamsadmin is used.

  • password (str) – Password for username If None, the password is taken from the STREAMS_PASSWORD environment variable. If the STREAMS_PASSWORD environment variable is not set, the default passw0rd is used to match the Streams Quick Start edition setup.

  • resource_url (str) – Root URL for IBM Streams REST API. If None, the URL is taken from the STREAMS_REST_URL environment variable. If the REST_URL environment variable is not set, then streamtool geturl --api is used to obtain the URL.

Example

>>> resource_url = "https://streamsqse.localdomain:8443/streams/rest/resources"
>>> sc = StreamsConnection("streamsadmin", "passw0rd", resource_url)
>>> sc.session.verify=False  # manually disable SSL verification, if needed
>>> instances = sc.get_instances()
>>> jobs_count = 0
>>> for instance in instances:
>>>     jobs_count += len(instance.get_jobs())
>>> print("There are {} jobs across all instances.".format(jobs_count))
There are 10 jobs across all instances.
session

Requests session object for making REST calls.

Type

requests.Session

get_domain(id)

Retrieves available domain matching a specific domain ID

Parameters

id (str) – domain ID

Returns

Domain matching id

Return type

Domain

Raises

ValueError – No matching domain exists.

get_domains()

Retrieves available domains.

Returns

List of available domains

Return type

list of Domain

get_installations()

Retrieves a list of all known Streams installations.

Returns

List of all Installation resources.

Return type

list of Installation

get_instance(id)

Retrieves available instance matching a specific instance ID.

Parameters

id (str) – Instance identifier to retrieve.

Returns

Instance matching id.

Return type

Instance

Raises

ValueError – No matching instance exists or multiple matching instances exist.

get_instances()

Retrieves available instances.

Returns

List of available instances

Return type

list of Instance

get_resources()

Retrieves a list of all known Streams high-level REST resources.

Returns

List of all Streams high-level REST resources.

Return type

list of RestResource

property resource_url

Root URL for IBM Streams REST API

Type

str

class streamsx.rest.StreamingAnalyticsConnection(vcap_services=None, service_name=None)

Bases: streamsx.rest.StreamsConnection

Creates a connection to a running Streaming Analytics service and exposes methods to retrieve the state of the service and its instance.

Parameters
  • vcap_services (str, optional) – VCAP services (JSON string or a filename whose content contains a JSON string). If not specified, it uses the value of VCAP_SERVICES environment variable.

  • service_name (str, optional) – Name of the Streaming Analytics service. If not specified, it uses the value of STREAMING_ANALYTICS_SERVICE_NAME environment variable.

Example

>>> # Assume environment variable VCAP_SERVICES has correct information
>>> sc = StreamingAnalyticsConnection(service_name='Streaming-Analytics')
>>> print(sc.get_streaming_analytics().get_instance_status())
{'plan': 'Standard', 'state': 'STARTED', 'enabled': True, 'status': 'running'}
get_domain(id)

Retrieves available domain matching a specific domain ID

Parameters

id (str) – domain ID

Returns

Domain matching id

Return type

Domain

Raises

ValueError – No matching domain exists.

get_domains()

Retrieves available domains.

Returns

List of available domains

Return type

list of Domain

get_installations()

Retrieves a list of all known Streams installations.

Returns

List of all Installation resources.

Return type

list of Installation

get_instance(id)

Retrieves available instance matching a specific instance ID.

Parameters

id (str) – Instance identifier to retrieve.

Returns

Instance matching id.

Return type

Instance

Raises

ValueError – No matching instance exists or multiple matching instances exist.

get_instances()

Retrieves available instances.

Returns

List of available instances

Return type

list of Instance

get_resources()

Retrieves a list of all known Streams high-level REST resources.

Returns

List of all Streams high-level REST resources.

Return type

list of RestResource

get_streaming_analytics()

Returns a StreamingAnalyticsService to allow further interaction with the Streaming Analytics service.

Returns

Object for interacting with the Streaming Analytics service.

Return type

StreamingAnalyticsService

static of_definition(service_def)

Create a connection to a Streaming Analytics service.

The single service is defined by service_def which can be one of

  • The service credentials copied from the Service credentials page of the service console (not the Streams console). Credentials are provided in JSON format. They contain such as the API key and secret, as well as connection information for the service.

  • A JSON object (dict) of the form: { "type": "streaming-analytics", "name": "service name", "credentials": {...} } with the service credentials as the value of the credentials key.

Parameters

service_def (dict) – Definition of the service to connect to.

Returns

Connection to defined service.

Return type

StreamingAnalyticsConnection

property resource_url

Root URL for IBM Streams REST API

Type

str