IBM InfoSphere Streams Version 4.1.1

Universal Resource Identifier patterns

Each REST API resource can be accessed by using a Uniform Resource Identifier (URI).

The URI must contain the correct connection information to successfully call the API. The connection information consists of the host name where the web management service is running, and the port number that the service is using. These values are represented by the server and port variables in the URI examples. To determine the server name and port number, run the streamtool geturl command.

The root URI for the InfoSphere® Streams REST API is https://server:port/streams/rest/resources. All other URIs can be retrieved by navigating through the responses that you receive when you query the resources URI. For example, the response includes the URI for the instance collection resource, which you can use to retrieve URIs for the jobs, processing elements, and hosts for an instance.

To determine the root URI, run the streamtool geturl command with the --api option.

Constructing URIs

In some cases, perhaps for efficiency reasons, you might prefer to directly access a resource instead of navigating to it from the root URI. When you access a resource directly, your application is tightly coupled with the server implementation. For compatibility reasons, use the root URI to navigate to resources as much as possible.

Many of the URI patterns are documented with replacement values in braces ({}). For example:

https://server:port/streams/rest/instances/{restid}/hosts/{restid}

A replacement value must be replaced with the value of the property of the same name for an element resource corresponding to the preceding path component. In this example, the first {restid} must be replaced with the restid property value for the instance to access, encoding as necessary. The second {restid} must be replaced with the restid property value for the host to access. For example:

https://server1.ibm.com:50826/streams/rest/instances/StreamsInstance/hosts/1.2.34.567

The restid property is used in URIs to uniquely identify a resource. Sometimes the restid property value has the same value as another property. For example, the value of the instance restid is the same as the value of the instance id property. Other times, the restid property value is generated from multiple property values. The value of the restid property alone might not uniquely identify a resource for a specific instance. For example, the combination of the job restid property value and the operator restid property value are needed to uniquely identify an operator within an instance.

Query parameters

The REST API supports the use of query parameters on many of the URIs. You can use the query parameters to filter, page, and sort the responses. Some resources also support extra query parameters. Query parameter names and values are case-sensitive.

Note: The REST API ignores any unexpected query parameters or values.