Introduction

In IBM App Connect Enterprise V11.0.0.5, the Integration API has been re-introduced so that you can administer your Integration Nodes, Integration Servers, and their deployed resources using a Java Application.

The REST Administration API is used by the Integration API to send requests and handle responses that are sent back. 

Here is an example REST request being made using curl to a local Integration Node and the JSON response that is sent back. The same REST request can be made using Java through the Integration API and model classes are provided which allow you to easily access specific fields in the response.

New Classes in Integration API

In ACE v11.0.05, these new Java packages and classes have been provided:

com.ibm.integration.admin.proxy

This package has new classes to use for administering an Integration Node, Integration Server, and deployed resources.

com.ibm.integration.admin.model

This package has classes that are a model representation of an Integration Node, Integration Server, and deployed resources. You can use get methods to access specific properties.

com.ibm.integration.admin.http

This package has classes that allow you to send direct requests and receive responses to/from a local or remote Integration Node or Integration Server.

com.ibm.integration.admin.logger

This package has classes that allow you to enable service trace to log requests and responses between your java client and the integration nodes or integration servers.

Classes in the package has com.ibm.broker.config.proxy are now deprecated. Limited capability is supported in V11. You should now look to migrating your Java code to use classes in com.ibm.integration.admin.proxy instead.

The classes are used to connect to the Node or Server over HTTP and issue REST requests to the Integration Node or Integration Server and process the REST responses. If the Node or Server is local, then the connection is made to a Unix Domain Socket or a Named Pipe (on windows).

Pre-requisite JAR Files

In order to use the Integration API to send REST requests and process the JSON responses, some JAR files must be added to your CLASSPATH. If you have run the mqsiprofile, then they are automatically added.

Proxy Classes

The IntegrationNodeProxy and IntegrationServerProxy classes in com.ibm.integration.admin.proxy are the starting point for using the Integration API.

You can connect to a local or remote Integration Node using the IntegrationNodeProxy class. It has the following constructors:

• To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
• To use the class with a local Integration Node, you just need to supply the name of the Integration Node.
• To use the class with a remote Integration Node, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password, and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

You can connect to a local or remote Integration Server using the IntegrationServerProxy class. Note that, you cannot connect to a node-owned server. It has the following constructors:

• To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
• To use the class with a local Integration Server, you just need to supply the name of the Integration Server and the location of the work directory.
• To use the class with a remote Integration Server, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password, and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

These ACE resources can be administered using the Integration API classes:

There is a Proxy class for each of the main resource types:

Model Classes

Each Proxy class has a corresponding Model class for processing the JSON response:

To process the JSON responses, the model classes in com.ibm.integration.admin.model, can be used to drill down into each response section to extract the piece of information that you are trying to access.

For example, the JSON response for the query on the Integration Node that was shown at the top of this article is modeled by these classes in the com.ibm.integration.admin.model.node package.

Model Caching

Each Proxy class will cache the Model after it has been obtained from the Integration Node or Integration Server. Each call to get the properties has a refresh option. If you need to refresh the model, set refresh to true otherwise it will return the existing model.

Example Code

Here is a simple code snippet which shows how to get a Proxy for a node-owned server called "Server1" and then look up a specific Application called "myApp" so that it can be stopped and then started again:

IntegrationServerProxy Class

The IntegrationServerProxy class allows you to administer several resources. There are getter methods for several resources:

You can also three different methods for deploying a BAR file:

• Specify the File object for the BAR file.
• Specify an InputStream and the name of the BAR file.
• Specify the path to the BAR file.

In addition, you can stop, start and delete deployed resources:

You can also stop and start an Integration Node-owned Integration Server, but you cannot start/stop an Independent Integration Server. In this case, an exception will be thrown.

ApplicationProxy, RestApiProxy, ServiceProxy, and MessageFlowProxy all have start/stop methods.

Debugging

Service trace can help diagnose any issues with your classes or help the IBM Support team to debug the issue. When running as a stand-alone Java application, tracing can be enabled using IntegrationAPI.class contained in package com.ibm.integration.admin.logger:

Below is a sample service trace of a call to getIntegrationServerByName:

HttpClient and HttpResponse

In addition to the Proxy and Model classes, there are two classes called HttpClient and HttpResponse which can be used to send a direct REST request and then process the REST response. These classes underpin the Proxy classes. You may want to use these classes if there is no specific method that you want to use in the Proxy classes.

The HTTPClient class can be used with a local or remote Integration Node or Integration Server. When accessing a local Integration Node or Integration Server, a Unix Domain Socket or Named Pipe is used.

HttpClient

The HttpClient allows you to use the different REST verbs: GET, POST, PATCH, and DELETE on ACE resources:

HttpResponse

The HttpResponse class can be used to access the REST response. It can be used to get the last URL request that was used by the IntegrationNodeProxy or IntegrationServerProxy by using the getUrlPath():

The parseResponseBody() method is useful to get a model representation of the response body, for example:

IntegrationNodeModel intNodeObject = 
lastHttpResponse.parseResponseBody(IntegrationNodeModel.class);

Example Code Using HttpClient and HttpResponse

The following code snippet shows how you can use the HttpClient and HttpResponse classes. It sends a REST request to a Node-owned Integration Server and uses the IntegrationServerModel class to parse the response. This is the equivalent of using the IntegrationServerProxy class and is shown for comparison. Obviously, it is easier to use the IntegrationServerProxy class as it does the bulk of the work for you!

You may want to use the HttpClient and HttpResponse classes to access deployed resources that do not have Proxy classes or Models, for example, deployed Policies or a specific Message Flow Node in a Message Flow.

Deprecated Classes

Classes in the package has com.ibm.broker.config.proxy are deprecated. Some classes like BrokerProxy and ExecutionGroupProxy can be used but not all. One way to ease your migration is to use BrokerProxy::getNewIntegrationNodeProxy() or ExecutionGroupProxy::getNewIntegrationServerProxy() methods. These methods return an IntegrationNodeProxy or IntegrationServerProxy representation of the Integration Node or Integration Server.  It is recommended to migrate to using classes in com.ibm.integration.admin.* packages.

Summary

In this article, I have described how to use the new packaged and classes in the Integration API provided in App Connect Enterprise v11.0.0.5.

The classes in com.ibm.integration.admin.proxy and com.ibm.integration.admin.model packages allow you to administer your Integration Node or Integration Server and their deployed resources. The HttpClient and HttpResponse classes underpin the Proxy classes. They can be used directly if required. 

The classes in com.ibm.broker.config.* are deprecated. It is strongly recommended for Java applications to be migrated to use the new classes in the com.ibm.integration.admin.* packages.

You can read further information about the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.doc/be43410_.htm

You can view the Javadoc for the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.cmp.doc/index.html?view=embed