Processing REST management API requests

To access information from Streams by using the REST management 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 management API.

About this task

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

Note: 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, 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 management API supports standard HTTP methods for accessing the resource that is identified by the URI.

The Streams REST management 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:32767/streams/resources
```
In this example,server1 is the IP address or host name and 32767 is the port number to use for access to the REST management API 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 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 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 com.google.gson.*;

import java.io.*;
import java.net.*;
import java.util.Base64;

import javax.net.ssl.*;

public class RestBasic {
    public static void main (String[] args) {
        try {
            System.setProperty("javax.net.ssl.trustStore", ".\\streams-rest.p12");
            System.setProperty("javax.net.ssl.trustStorePassword", "Streams-Rest-Passw0rd%");

            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://myserver.mybusiness.com:9714/streams/domains/d-dev72");
            String userInfo  = "joeuser" + ":" + new String("Tr1ckyS3cr3tPhras3!");
            String authToken = "Basic " + Base64.getEncoder().encodeToString(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();

            try (InputStreamReader responseStreamReader = new InputStreamReader(responseStream)) {
                JsonObject jsonResult = new Gson().fromJson(responseStreamReader, JsonObject.class);
                String id = jsonResult.get("id").getAsString();
                System.out.println("Domain id = " + id);
            } 
            conn.disconnect();
        }
        catch (Exception e) {
            System.out.println("Exception: " + e.getMessage()); 
        }
    }
}