Foglight 7.1.0 - REST API Reference Guide

Content Type

The Foglight REST API cartridge supports mapping data to both JSON and XML formats. Using the JSON format is preferred for both the @Produces and @Consumes annotations.

For example:

API Validation

A custom REST API can use Java Bean Validation annotations to specify constraints on the data passed to the REST API. For example, the following class that is used as the body of a request could be defined with an annotation to ensure that the host name in the request body is not null.

The API method could then use the @Valid annotation to indicate that the message body should be validated:

Securing the Endpoint

Custom REST APIs should add the @Secured annotation to either the JAX-RS resource class, or to the method, to ensure that requests sent to the endpoint are authenticated and authorized. If the annotation is added, then the request headers must contain either an Access-Token or Auth-Token header. If there is no @Secured annotation added, then there will not be any security applied to the endpoint, and requests from any anonymous users will be processed.

If the @Secured annotation is added without any arguments, then the user making the request must have the API Access role to be able to invoke the API.

If the @Secured annotation contains additional parameters to specify one or more roles (for example, @Secured({"Operator", "Advanced Operator"}) ), then the user must have one of the specified roles to be able to invoke the API. In this case, it is not required for the user to also have the API Access role. However, if the @Secured annotation specifies multiple roles, and includes the API Access role (for example, @Secured({"API Access", "Advanced Operator"}) ), then the user must have the API Access role, and must additionally have one of the other roles specified in the annotation.

Accessing Foglight Services

The REST API implementation may need to invoke Foglight Java APIs to execute the intended operation. The ServiceLocator interface in the Foglight Java API is used to obtain a reference to the various Foglight services on which API methods can then be invoked. To ensure that any API methods are run in the context of the user that invoked the REST API, the Foglight REST API cartridge provides a ServiceLocator instance that uses the JAX-RS SecurityContext to identify the user that is invoking the API. A custom REST API implementation can obtain this instance by using the @Inject annotation on a member variable in the resource class. For example:

The ServiceLocator instance can then be used for any interaction with Foglight APIs. For example: