IBM Streams 4.3.0

Processing REST API requests

To access information from IBM® Streams by using the REST API, your application must send a valid HTTP request. The application must then handle the HTTP response.

Before you begin

Configure security for the REST API.

About this task

The objects that you can access with the IBM Streams REST API are referred to as resources.

Note: The concept of REST API resources is different from the general concept of resources in IBM Streams. A REST API resource refers an object with properties and relationships to other resources. An IBM Streams resource refers to an entity on which stream processing applications and IBM Streams services can be run, for example a host. For more information, see Resources.

Each resource can be identified by a uniform resource identifier (URI). You can also add query parameters to the URI to tailor and filter response content. The REST API supports standard HTTP methods for accessing the resource that is identified by the URI.

The IBM Streams REST API uses the JavaScript Object Notation (JSON) format for message content.

Procedure

Construct the URI for the resource that you want to access. For example:
```
https://server1:8443/streams/rest/resources
```
In this example, server1 and 8443 are the host name and port number for the web management service.
Specify the appropriate HTTP method in your application. For example, use the GET method to query a resource. Set any HTTP request headers and configure the request message body as necessary. If any cookies were returned in the Set-Cookie header of a previous IBM Streams REST call, include these cookies in the Cookie header. Retaining cookies between requests helps your application performance.
Establish an HTTPS connection in your application and send the request to the IBM Streams server.
Process the HTTP status code, response headers, and any response message that are returned. Retain cookies that are returned in the Set-Cookie header so that they can be sent with subsequent requests.

Example

The following example Java™ code retrieves the root resource information in a scenario where client authentication is enabled. In this example, user authentication is handled by using HTTP basic authentication:

import java.io.*;
import java.net.*;
import javax.net.ssl.*;
import javax.xml.bind.DatatypeConverter;
import com.ibm.json.java.JSONObject;

public class RestBasic {
  public static void main (String[] args) {
    try {
      System.setProperty("javax.net.ssl.trustStore", ".\\ibmjsse2.jks");
      System.setProperty("javax.net.ssl.trustStorePassword", "ibmpassw0rd");

     HostnameVerifier hv = new HostnameVerifier() {
          public boolean verify(String urlHostName, SSLSession session) {
              return true;   // trust all hosts that supply the Streams certificate
          }
      };
      HttpsURLConnection.setDefaultHostnameVerifier(hv);

      // Retain cookies between requests
      CookieManager cm = new CookieManager();
      CookieHandler.setDefault(cm);

      URL url = new URL("https://server5.ibm.com:8456/streams/rest/domains/test6");
      String userInfo  = "bsmith" + ":" + new String("secret");
      String authToken = "Basic " + DatatypeConverter.printBase64Binary(userInfo.getBytes());
      HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();

      conn.setRequestProperty("Authorization", authToken);
      conn.setRequestMethod("GET"); 
      conn.connect();
      System.out.println("Response code: " + conn.getResponseCode());
      System.out.println("Content type: " + conn.getHeaderField("Content-Type"));

      InputStream  responseStream = conn.getInputStream();
      InputStreamReader responseStreamReader = new InputStreamReader(responseStream);
      
      JSONObject jsonResult = JSONObject.parse(responseStreamReader);
      String id = (String)jsonResult.get("id");
      System.out.println("Domain id = " + id);

      conn.disconnect();
    }
    catch (Exception e) {
      System.out.println("Exception: " + e.getMessage()); 
    }
  }
}