Foglight 7.1.0 - REST API Reference Guide

Exception Handling

The REST API cartridge provides default handling of some exceptions. Any validation errors occuring on the request arguments will be handled and will result in a “Bad Request” (400) status code. Any uncaught exceptions will be automatically handled by the REST API cartridge and will result in an “Internal Server Error” (500) status code. Error information is returned using an error object with the following structure:

Registering the Custom REST API

The REST API cartridge exposes a ForgeRestApiExtension interface that is used to register new REST APIs. The cartridge that defines the custom REST API must have a dependency on the Forge-RestAPI cartridge for the extension interface to be visible. The cartridge should then define a Java class that implements the interface, and provides a reference to the JAX-RS resource class. The following is an example of a custom ForgeRestApiExtension class for a specific resource class:

The cartridge should define a lifecycle class that implements both the LifecycleAware and ExtensionContextAware interfaces. This class should be configured to instantiate with the cartridge deployment, enabling it to receive cartridge lifecycle events.

For example:

The cartridge that is created should include a component that deploys the JAR file containing the custom REST API and specifies that the lifecycle class should be instantiated during the deployment of the cartridge;

Using Groovy-based Custom REST APIs

It is also possible to use a Groovy script to define the JAX-RS resource class, and to then register the REST API extension. The following Groovy script is an example.

NOTE: The /*Hint: ...*/ comment must appear as the first line on the script in order for it to be processed correctly on the FMS. The script will also need to be run in the context of the Forge-RestAPI cartridge to allow the extension interface classes to be resolved.

Any REST APIs registered with this approach will remain registered until the Foglight Management Server shuts down. The script will need to be re-run when the server is restarted. If the scripts are packaged in a cartridge, it would be possible to use a class that implements the LifecycleAware interface to run the script from the start() method.