Processing REST API requests to the IBM Streams security service

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

About this task

The objects that you can access with the Streams REST API are referred to as resources. The concept of REST API resources is different from the general concept of resources in Streams. A REST API resource refers an object with properties and relationships to other resources. A Streams resource refers to an entity on which stream processing applications and Streams services can be run.

Each resource can be identified by a uniform resource identifier (URI). You can 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 Streams REST API uses the JavaScript Object Notation (JSON) format for message content.

Procedure

  1. Construct the URI to retrieve security realm access token.
    For example:
    https://server1:32767/streams/rest/security/realms/myRealm/accesstokens
    In this example, server1 is the IP address or hostname and 32767 is the port number to use for access to the security service.
  2. Specify the appropriate HTTP method in your application. For example, use the POST method to retrieve an access token. 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 Streams REST call, include these cookies in the Cookie header. Retaining cookies between requests helps your application performance.
  3. Establish an HTTPS connection in your application and send the request to the Streams server.
  4. 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 a JWT access token for the myRealm security realm. 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.JSONArray;
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/security/realms/myRealm/accesstokens");
      String userInfo  = "bsmith" + ":" + new String("secret");
      String authToken = "Basic " + DatatypeConverter.printBase64Binary(userInfo.getBytes());
      HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();

      JSONObject json = new JSONObject();
      JSONArray audience = new JSONArray();
      json.put("audience", audience);
      audience.put("streams");
      String request = json.serialize();
      
      conn.setRequestProperty("Authorization", authToken);
      conn.setRequestMethod("POST");
      conn.setRequestProperty("Content-Type", "application/json");
      conn.setRequestProperty("Content-Length", Long.toString(request.length()));           
      conn.setDoOutput(true);
      conn.connect();
      
      OutputStream os = http.getOutputStream();
      os.write(request.getBytes());
      os.close();
            
      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 accessToken = (String)jsonResult.get("accessToken");
      System.out.println("accessToken = " + accessToken);

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