• org.labkey.api.action.ReadOnlyApiAction
• org.labkey.api.action.MutatingApiAction

Topics:

• Overview
• API Action Design Rules
• API Actions
• Execute Method
• Form Parameter Binding
• Jackson Marshalling (Experimental Feature)
• Error and Exception Handling

Overview

API actions build upon LabKey’s controller/action design. They include one of the “API” action base classes whose derived action classes interact with the database or server functionality. These derived actions return raw data to the base classes, which serialize raw data into one of LabKey’s supported formats.

Leveraging the current controller/action architecture provides a range of benefits, particularly:

• Enforcement of user login for actions that require login, thanks to reuse of LabKey’s existing, declarative security model (@RequiresPermission annotations).
• Reuse of many controllers’ existing action forms, thanks to reuse of LabKey’s existing Spring-based functionality for binding request parameters to form beans.

API Action Design Rules

In principle, actions are autonomous, may be named, and can do whatever the controller author wishes. However, in practice, we suggest adhering to the following general design rules when implementing actions:

• Action names should be named with a verb/noun pair that describes what the action does in a clear and intuitive way (e.g., getQuery, updateList, translateWiki, etc.).
• Insert, update, and delete of a resource should all be separate actions with appropriate names (e.g., getQuery, updateRows, insertRows, deleteRows), rather than a single action with a parameter to indicate the command.
• Wherever possible, actions should remain agnostic about the request and response formats. This is accomplished automatically through the base classes, but actions should refrain from reading the post body directly or writing directly to the HttpServletResponse unless they absolutely need to.
• For security reasons, actions that respond to GET should not mutate the database or otherwise change server state. Actions that change state (e.g., insert, update, or delete actions) should only respond to POST and extend MutatingApiAction.

API Actions

An API Action is a Spring-based action that derives from one of the abstract base classes:

• org.labkey.api.action.ReadOnlyApiAction
• org.labkey.api.action.MutatingApiAction

@RequiresPermission(ReadPermission.class) 
public class GetSomethingAction extends MutatingApiAction<MyForm>
{
    public ApiResponse execute(MyForm form, BindException errors) throws Exception
    {
        ApiSimpleResponse response = new ApiSimpleResponse();

        // Get the resource...
        // Add it to the response...

        return response;
    }
}

JSON Example

A basic API action class looks like this:

@RequiresPermission(ReadPermission.class)
public class ExampleJsonAction extends MutatingApiAction<Object>
{
    public ApiResponse execute(Object form, BindException errors) throws Exception
    {
        ApiSimpleResponse response = new ApiSimpleResponse();

        response.put("param1", "value1");
        response.put("success", true);

        return response;
    }
}

A URL like the following invokes the action:

http://localhost:8080/labkey/mymodule/home/exampleJson.view

Returning the following JSON object:

{
  "success" : true,
  "param1" : "value1"
}

Example: Set Display for Table of Contents

@RequiresLogin
public class SetTocPreferenceAction extends MutatingApiAction<SetTocPreferenceForm>
{
	public static final String PROP_TOC_DISPLAYED = "displayToc";

	public ApiResponse execute(SetTocPreferenceForm form, BindException errors)
	{
		//use the same category as editor preference to save on storage
		PropertyManager.PropertyMap properties = PropertyManager.getWritableProperties(
			getUser(), getContainer(),
			SetEditorPreferenceAction.CAT_EDITOR_PREFERENCE, true);
		properties.put(PROP_TOC_DISPLAYED, String.valueOf(form.isDisplayed()));
		PropertyManager.saveProperties(properties);

		return new ApiSimpleResponse("success", true);
	}
}

Execute Method

public ApiResponse execute(FORM form, BindException errors) throws Exception

In the execute method, the action does whatever work it needs to do and responds by returning an object that implements the ApiResponse interface. This ApiResponse interface allows actions to respond in a format-neutral manner. It has one method, getProperties(), that returns a Map<String,Object>. Two implementations of this interface are available: ApiSimpleResponse, which should be used for simple cases; and ApiQueryResponse, which should be used for returning the results of a QueryView.

ApiSimpleResponse has a number of constructors that make it relatively easy to send back simple response data to the client. For example, to return a simple property of “rowsUpdated=5”, your return statement would look like this:

return new ApiSimpleResponse("rowsUpdated", rowsUpdated);

where rowsUpdated is an integer variable containing the number of rows updated. Since ApiSimpleResponse derives from HashMap<String, Object>, you may put as many properties in the response as you wish. A property value may also be a nested Map, Collection, or array.

The mutating or read-only action base classes take care of serializing the response in the JSON appropriate format.

Although nearly all API actions return an ApiResponse object, some actions necessarily need to return data in a specific format, or even binary data. In these cases, the action can use the HttpServletResponse object directly, which is available through getViewContext().getReponse(), and simply return null from the execute method.

Form Parameter Binding

If the request uses a standard query string with a GET method, form parameter binding uses the same code as used for all other view requests. However, if the client uses the POST method, the binding logic depends on the content-type HTTP header. If the header contains the JSON content-type (“application/json”), the API action base class parses the post body as JSON and attempts to bind the resulting objects to the action’s form. This code supports nested and indexed objects via the BeanUtils methods.

For example, if the client posts JSON like this:

{ "name": "Lister",
  "address": {
    "street": "Top Bunk", 
    "city": “Red Dwarf", 
    "state": “Deep Space"},
  "categories” : ["unwashed", "space", "bum"]
}

The form binding uses BeanUtils to effectively make the following calls via reflection:

form.setName("Lister");
form.getAddress().setStreet("Top Bunk");
form.getAddress().setCity("Red Dwarf");
form.getAddress().setState("Deep Space");
form.getCategories().set(0) = "unwashed";
form.getCategories().set(1) = "space";
form.getCategories().set(2) = "bum";

Where an action must deal with the posted data in a dynamic way (e.g., the insert, update, and delete query actions), the action’s form may implement the CustomApiForm interface to receive the parsed JSON data directly. If the form implements this interface, the binding code simply calls the setJsonObject() method, passing the parsed JSONObject instance, and will not perform any other form binding. The action is then free to use the parsed JSON data as necessary.

Jackson Marshalling (Experimental)

Experimental Feature: Instead of manually unpacking the JSONObject from .getJsonObject() or creating a response JSONObject, you may use Jackson to marshall a Java POJO form and return value. To enable Jackson marshalling, add the @Marshal(Marshaller.Jackson) annotation to your Controller or Action class. When adding the @Marshal annotation to a controller, all actions defined in the Controller class will use Jackson marshalling. For example,

@Marshal(Marshaller.Jackson)
@RequiresLogin
public class ExampleJsonAction extends MutatingApiAction<MyStuffForm>
{
    public ApiResponse execute(MyStuffForm form, BindException errors) throws Exception
    {
        // retrieve resource from the database 
        MyStuff stuff = ...;

        // instead of creating an ApiResponse or JSONObject, return the POJO
        return stuff;
    }
}

Error and Exception Handling

If an API action adds errors to the errors collection or throws an exception, the base action will return a response with status code 400 and a json body using the format below. Clients may then choose to display the exception message or react in any way they see fit. For example, if an error is added to the errors collection for the "fieldName" field of the action's form class with message "readable message", the response will be serialized as:

{
    "success": false,
    "exception": "readable message",
    "errors": [ {
        "id" : "fieldName",
        "msg" : "readable message",
    } ]
}