Introduction to the Remote API

18/10/2007 10:08 by Sten Roger Sandvik

Most of the public API methods in Vertical Site are also exposed remote. We have two methods of accessing the remote API: binary protocol and SOAP protocol. The binary protocol is proprietary, but faster and easier. If the need for a standard protocol arises, SOAP is the way to go. In this article, I will here describe the binary method of connecting to the remote API.

Dependencies

To start off easy, we will begin with the binary protocol. The binary protocol has a pure Java API and can only be accessed in Java. If .NET is the client platform, the binary API will not work. For all other client platforms than Java, SOAP is the recomended protocol.

When using the binary protocol, we need a couple of Java dependencies to make it work:

• JDOM 1.0 (Easy to use XML/DOM library)
• CMS-API 4.1.x or later (Vertical Site API module)

Both of the libraries are found under api/lib in the installation folder. If you are using Maven as a build system, you can install the cms-api module into local repository by running the following command:

mvn install:install-file -DgroupId=com.enonic.cms -DartifactId=cms-api 
  -Dpackaging=jar -Dversion=4.1.6 -Dfile=cms-api.jar

Please note that if other version is used, replace 4.1.6 with the actual version. After the artifact installation, place the following dependencies into your project model file (pom.xml):

<dependencies>
  <dependency>
    <groupId>jdom</groupId> 
    <artifactId>jdom</artifactId>  
    <version>1.0</version>
  </dependency>
  <dependency>
    <groupId>com.enonic.cms</groupId>
    <artifactId>cms-api</artifactId>
    <version>4.1.6</version>
  </dependency>
</dependencies>

Connecting the Client

The first thing to do is to find the service endpoint url of your installation. If you have installed locally, the endpoint url would then normally be:

• http://localhost:8080/cms/rpc/bin (Binary protocol)
• http://localhost:8080/cms/rpc/soap (SOAP protocol)

Second, you need to import the required packages in your project.

// Importing required packages
import com.enonic.cms.api.client.*;
import com.enonic.cms.api.client.binrpc.*;
import com.enonic.cms.api.client.model.*;

Next step is to create the remote client. It only exists one concrete implementation in the cms-api module: BinRpcRemoteClient.

// Connecting to the server
Client client = new BinRpcRemoteClient("http://localhost:8080/cms/rpc/bin");

// Printing out the user and run-as-user
System.out.println("user = " + client.getUser());
System.out.println("runAsUser = " + client.getRunAsUser());

Login and Impersonate

When the client has been connected to the server, you are automatically logged in as anonymous. To log into the system with another user, call login method on the client:

// Logging in as admin
client.login("admin", "mypassword");

// Logging in as user on domain 0
client.login("0:user", "mypassword");

Logging in as another user than admin requires a domain key prefix like 0:user. When logged into the client with the enterprise administrator user, you can impersonate any users. So, instead of logging into the server with a password, you can then skip the password by impersonating the user.

            
// Logging in as admin
client.login("admin", "mypassword");

// Impersonating the user on domain 0
client.impersonate("0:user");

// Printing out the run-as user
System.out.println("runAsUser: " + client.getRunAsUser());

As you can see above, we print out the run-as user. When impersonating, the run-as user is the actual impersonated user and the user is the user logged into the system. You can impersonate different users in the same session.

Invoking Operations

Before, we have only used the security functions. Now I will illustrate the actual invoking of the core methods. Exposed core methods is the same as datasources in Vertical Site, but only invoked in a remote fashion. All core methods has the concept of parameter objects instead of a long parameter list. The reason for this is to allow optional parameters to be omitted.

Most core methods return an XML document. This document is in the form of a DOM (Document Object Model) and the implementation we use for this is JDOM. Therefore, when using the core methods we need an extra import statement:

// Importing the required JDOM classes
import org.jdom.*;

I will only illustrate some methods here. To see all other methods available, please look at the generated javadoc.

// Creating the parameters
GetCategoriesParams params = new GetCategoriesParams();
params.categoryKey = 17;

// Invoke the categories operation
Document xml = client.getCategories(params);

// Creating the parameters with more values
params = new GetCategoriesParams();
params.categoryKey = 17;
params.includeContentCount = true;
params.levels = 2;

// Invoke the categories operation
xml = client.getCategories(params);

One interesting method in the core api is renderPage. This method renders the page remotely and return the actual markup generated. The method is intended to be used in integrations with existing frontends.

// Creating the render parameters
RenderPageParams params = new RenderPageParams();
params.menuItemKey = 90;
params.basePath = "/mybase";

// Invoking the render operation
Document xml = client.renderPage(params);

// Finding the markup
String markup = xml.getRootElement().getChildText("markup");