Basic API access

All access to the REST API is made through the Deep Security Manager URL https://<host or IP>:<port>/rest. For example, if Deep Security Manager is installed on a computer named dsm.example.com and is listening on the default REST API port number, the URL is:

https://dsm.example.com:4119/rest

Because the REST API uses standard HTTP mechanisms and some of the operations can be accessed without authentication using HTTP GET, these methods can be accessed from a web browser. For example, the following URL returns the REST API version to the browser:

https://dsm.example.com:4119/rest/apiVersion

However, most REST API calls require authentication. To authenticate calls, you provide a session identifier (SID) either as a query parameter for GET and DELETE methods or in the message body of PUT and POST methods. To get a session ID, call the /rest/authentication/login URL with the user name and password of a user who is allowed to access the API.

Manage your sessions

Take the following actions to manage your sessions:

• Terminate API sessions when they are no longer required. The Deep Security Manager limits the number of sessions that can be active at one time. Your application should terminate its sessions to avoid reaching the maximum number of concurrent sessions. Call the /rest/authentication/logout URL to end the session
• Sessions time out after a configurable period. To change the number of concurrent sessions allowed per user and the session timeout, go to Administration > System Settings > Security.

The example Java code below illustrates this process.

Use the provided Java REST API client

The provided Java REST API client is based on the RESTEasy Client Framework and the Apache HTTPComponents project. This framework takes the Java interfaces that have been marked up with JAX-RS annotations and generates implementations of the interfaces that can communicate with the Deep Security Manager. The Java REST  API client takes care of all object serialization and deserialization, HTTP URLs, and HTTP methods for you.

To use the Java REST API client, include the JAR file in the lib folder on the classpath of your application. The JAR file has dependencies on other third-party libraries. For details, see the pom.xml file of the Eclipse project in the samples directory.

The interfaces for all the APIs are found in the Java package com.trendmicro.ds.platform.rest.api. All of the objects sent to or from the API are found in the Java package com.trendmicro.ds.platform.rest.object and sub-packages.

Example Java code

The following example code uses the Java REST API client to authenticate with Deep Security Manager.

import javax.ws.rs.core.Response.Status;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ClientResponseFailure;
import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor;
import org.jboss.resteasy.plugins.providers.RegisterBuiltin;
import org.jboss.resteasy.spi.ResteasyProviderFactory;

import com.trendmicro.ds.platform.rest.api.IAuthenticationAPI;
import com.trendmicro.ds.platform.rest.message.error.ErrorMessage;
import com.trendmicro.ds.platform.rest.object.DSCredentials;

public class AuthenticateSample {

    public static void main(String[] args) {
        // URL for the REST API. Change this as appropriate. 
        String restApiUrl = "https://10.0.0.5:4119/rest";

        // The user name to use for authentication. Change this as appropriate.
        String username = "admin";

        // The user's password. Change this as appropriate.
        String password = "supersecretpassword";

        // Variable to store the session identifier (SID).
        String sID = null;

        // RESTEasy client framework initialization that only needs to be done once per VM
        RegisterBuiltin.register(ResteasyProviderFactory.getInstance());

        // An object that will execute HTTP requests
        ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();

        // Create the object that will communicate with the authentication API.
        IAuthenticationAPI authClient = ProxyFactory.create(IAuthenticationAPI.class, restApiUrl, executor);

        // Create the object to pass to the authentication call.
        DSCredentials credentials = new DSCredentials();
        credentials.setUserName(username);
        credentials.setPassword(password);

            try {
                System.out.println("Attempting to authenticate to Deep Security Manager REST API...");
                sID = authClient.login(credentials);

                System.out.println("Authentication successful.");
                System.out.println("Authentication session ID string received: " + sID);

            } catch (ClientResponseFailure e) {
                // This is a special type of exception that means the server threw
                // an exception because there was a problem with the credentials.
                // It's important to handle these exceptions explicitly or the
                // connection to the server won't be released back in to the
                // underlying connection pool, meaning any subsequent API calls would fail.
                // See the RESTEasy Client Framework documentation for more details. 
                ClientResponse<?> clientResponse = e.getResponse();

                // Try to parse the error response in to an instance of the special
                // ErrorMessage class and display the result.
                Status status = clientResponse.getResponseStatus();
                System.out.println("Server returned error status code " + status.getStatusCode() + " (" + status + ")");
                ErrorMessage errorMessage = clientResponse.getEntity(ErrorMessage.class);
                System.out.println("Returned error message: " + errorMessage.getMessage());

            } catch (Exception e) {
                // Some other error happened, most likely related to network communication problems.
                System.out.println("There was an error during authentication.");
                e.printStackTrace();

            } finally {
                if (sID != null) {
                    // Make sure to always log out.
                    System.out.println("");
                    System.out.println("Ending session...");
                    authClient.endSession(sID);
                    System.out.println("End session successful.");
                    // make sure the session ID isn't accidentally re-used.
                    sID = null;
                }
            }

            // Cleanup: force the HTTP Client to close any open sockets
            executor.close();

    }

}

Use the Sample Java code

Sample Java code is included in the samples folder. The samples are part of an Eclipse project that you can import into your Eclipse workspace:

1. In Eclipse, click File > Import.
2. Select General > Existing Projects into Workspace for the import source.
3. Click Browse and select the samples folder of the Deep Security Web Services SDK as the root.
4. Ensure the REST API Samples project is selected and click Finish.

To run a sample file within Eclipse, open the file and click Run > Run As > Java Application. The samples require command line arguments that you need to set on the Run Configurations screen.

HTTP status codes

The REST API uses standard HTTP status codes to return the status of requests. The table below shows the response codes that may be used and the circumstances under which they are returned.

Error responses

When an API call returns a status code other than 200 OK, the response body typically  includes JSON code similar to the following example:

{
   "error": {
      "message": "The Activation Code KA47-R947M-KDLUZ-A8WLF-WM6A3-LOL is invalid."
   }
}

Some calls include XML code instead of JSON, as in the following example:

<error>
    <message>Error message string</message>
</error>

The error message can be helpful for debugging the problem but is not suitable for presenting to end users of an application.

API calls that return javax.ws.rs.core.Response

Some API calls are documented as returning an object of type javax.ws.rs.core.Response. These calls can be thought of as returning nothing more than the HTTP status code.

When you use the provided Java REST API client, it is important to retrieve the result of such calls instead of ignoring them. Once you have the Response object, the underlying connection to the server must be manually released back to the connection pool, as described in the RESTEasy Client Framework. For example:

org.jboss.resteasy.client.ClientResponse<?> clientResponse = (ClientResponse<?>)apiObject.methodThatReturnsResponse(methodParameters); clientResponse.releaseConnection();