Extending the REST Manager API

The 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 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 wish 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 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. 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/v2/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.

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, @MatrixParam
• Other: @Consumes, @Produces