REST Manager API

The Manager provides a REST REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. Manager API for managing the GigaSpaces application environment.

To begin, start a standalone GigaSpaces Manager on your machine using the following command:

./gs.sh host run-agent --auto --restv3 --webui

gs host run-agent --auto --restv3 --webui 

Long-Running Operations

In the Admin API, long-running operations (for example, deploy and undeploy) are asynchronous with no future or callback. You can either track progress manually, or use various 'andWait' overloads (for example, deployAndWait). The REST Manager API cannot use andWait, so you must poll for completion, but each such operation behaves differently.

Instead, the REST Manager API contains Request functionality. Each long-running operation creates a request and returns its ID, so you can poll on the request ID and check the status (running/successful/failed). The request exposes additional useful information:

• Who started the request (IP and user)

• When the request was started and completed

• If the request failed, an error message

• Additional properties on the request execution

By default, the system keeps up to 100,000 completed requests (configurable), and purges the oldest as needed.

Processing Unit Deployment and Upload

Deploying a Processing Unit This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. requires uploading a resource (JAR/WAR/ZIP) to the GigaSpaces Manager, but due to technical limitations it is currently not possible to include both a binary file and a JSON payload in the same REST operation. Instead, there are two separate operations:

• Upload a resource.

• Deploy a Processing Unit, and provide the name of a previously uploaded resource.

This also means that when you undeploy a Processing Unit, the resource is not deleted. If you want to delete it you must execute a separate REST operation (if you want to undeploy/redeploy with the same JAR, there is no need to remove it). Currently you cannot delete or replace a JAR file if a deployed Processing Unit is using it.

Security

The REST component is part of the GigaSpaces Manager, and inherits the GigaSpaces Manager security configuration. As the REST API uses the HTTP protocol, it is best to configure SSL to allow for HTTPS (secure access).

Enabling Security

The REST Manager API allows for secured access and operations when the security enabled property is set. This property should be configured using the GS_OPTIONS_EXT in the setenv script, and is applied to all GigaSpaces Grid Components.

The property:

-Dcom.gs.security.enabled=true

SSL Configuration

Basic authentication does not encrypt user credentials, so running a GigaSpaces Manager in a secure environment without SSL is a security hazard; the system detects this and aborts. You must explicitly enable or disable SSL by setting the system property com.gs.manager.rest.ssl.enabled.

You can do one of the following:

• Disable SSL explicitly (not recommended).

• Enable SSL, and the system will generate a certificate for you.

• Enable SSL and provide a trusted certificate that you own.

An auto-generated certificate provides reasonable security, but if your enterprise security guidelines are more strict you can provide your own certificate.

Finally, if you need to configure something that is not exposed (Jetty is used under the hood to host the web app), you can provide your own jetty.xml file via a system property.

Security Properties File

The security properties file is used to configure the SecurityManager, that is responsible for the authentication and authorization process. The security.properties file is common to all components and is usually located under $GS_HOME/config/security/security.properties.

The REST component is part of the GigaSpaces Grid components. To only affect the Grid components, use the grid-security.properties instead.

The configuration file can be located anywhere in the classpath or in the classpath under config/security.

Alternatively, a system property can be set to indicate the location of the properties file:

-Dcom.gs.security.properties-file = my-security.properties

By setting -Dcom.gs.security.properties-file, the property file will be located as a direct path (e.g. ~/home/user/my-security.properties), a resource (e.g. my-security.properties) in the classpath, or in the classpath under config/security.

Online Editor

Extending The REST Manager API

The REST Manager API is extensible so that custom methods can be added. Developers can implement a plain Java class with JAX-RS annotations.

Sample Implementation

Follow the instructions below to create a sample extension for the REST Manager API:

1. Create a class and annotate it with com.gigaspaces.manager.rest.CustomManagerResource.

2. Create a method for each path you wish to intercept, and annotate it with an HTTP operation (e.g. @GET) and a @Path annotation with the relevant path.

3. Use JAX-RS parameter annotations (e.g. @QueryParam) to map HTTP request parameters to your method.

4. If you want to use Admin, create an appropriate field and annotate it with JAX-RS @Context annotation.

For example:

@CustomManagerResource
@Path("/demo")
public class BasicPluggableOperationTest {
    @Context Admin admin;

    @GET
    @Path("/report")
    public String report(@QueryParam("hostname") String hostname) {
        Machine machine = admin.getMachines().getMachineByHostName(hostname);
        return "Custom report: host=" + hostname + 
                ", containers=" + machine.getGridServiceContainers() + 
                ", PU instances=" + machine.getProcessingUnitInstances();
    }
}

This class maps an HTTP GET operation in the /demo/report path to a report method. It accepts a query parameter, and uses an injected Admin instance to perform user-defined code (in this case, a custom report). For example, http://localhost:8090/demo/report?hostname=mypc.

To run the example, compile it and package it into a .jar file, then copy the .jar to $GS_HOME/lib/platform/manager/plugins and start the GigaSpaces Manager.

Note that some JAX-RS features are not supported - see JAX-RS Support below for detailed information.

Configuration

When the GigaSpaces Manager starts, it scans the $GS_HOME/lib/platform/manager/plugins for classes in the jar files with the JAX-RS annotations and registers them. You can override the location using the following system property:

com.gs.manager.rest.plugins.path="pathToJar"

Response

In the example above the method returns a String, and in addition it implicitly returns an HTTP code 200 (OK). If you need to explicitly specify the HTTP result code, use org.openspaces.admin.rest.Response instead of a String.

For example:

import org.openspaces.admin.rest.Response

@GET
@Path("/report")
public Response report(@QueryParam("hostname") String hostname) {
    Machine machine = admin.getMachines().getMachineByHostName(hostname);
    if (machine == null)
        return Response.status(javax.ws.rs.core.Response.Status.NOT_FOUND).entity("Host not found").build();    
    String result = "Custom report: host=" + hostname + 
            ", containers=" + machine.getGridServiceContainers() + 
            ", PU instances=" + machine.getProcessingUnitInstances();
    return Response.ok().entity(result).build();
}

Security

To define security privileges for a custom method, you have to import org.openspaces.admin.rest.PrivilegeRequired and org.openspaces.admin.rest.RestPrivileges, and use @PrivilegeRequired. The @PrivilegeRequired annotation accepts a RestPrivileges enum that corresponds to the Security privileges.

For example:

import org.openspaces.admin.rest.PrivilegeRequired
import org.openspaces.admin.rest.RestPrivileges

@CustomManagerResource
@Path("/secured/")
public class PluggableSecuredContoller {
    @Context Admin admin;

    @PrivilegeRequired(RestPrivileges.MANAGE_GRID)
    @GET
    @Path("/getBase")
    public String getBase() {
        return "hello";
    }
}

JAX-RS Support

The JAX-RS API is used for extension support because it is a well-known standard and commonly used by developers. The sections below list the annotations that are supported, and those that are not supported.

Supported Annotations

The following JAX-RS annotations are supported:

• HTTP operations: @GET, @PUT, @POST, @DELETE

• Parameters: @QueryParam, @PathParam, @DefaultValue

  • Supported types: Java primitive types ("int', "long', etc.) and String

• Other: @Context

  • Fields only (No support for constructors or method arguments)

  • Supported types: Admin

Unsupported Annotations

The following JAX-RS annotations are not supported:

• HTTP operations: @OPTIONS, @HEAD

• Parameters: @FormParam, @HeaderParam, @CookieParam, @Matrix