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.

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.

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 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 host name and 32767 is the port number to use for access to the security service.
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 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 retreives 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()); 
    }
  }
}