Plugin developers can add RESTful web services to Casa easily. Simply create your resource classes and use JAX-RS 2.0 annotations such as
@POST, etc. so when a plugin is started all endpoints are dynamically added.
There is no need to add extra dependencies to your project. Module
casa-shared already includes most of what you'll need. In summary, the following is required to add a RESTful service:
- Create a class in your plugin (any package and file name is fine)
- Annotate the class with
javax.ws.rs.Pathand supply a value for the annotation
- Annotate the class with
org.gluu.casa.rest.RSResourceScopeif you want to specify whether the resource should be treated as a singleton or a new instance should be created upon every request. If not used, default behavior will be "singleton"
- Add methods with annotations such as
@POST, etc. (i.e. implement your service)
Services created this way will be available at the URL
path is the value supplied in step 2.
By default, all services are anonymously accessible. In case you want to protect your endpoints, Casa allows you to do so by means of an OAuth token, that is, clients of the service must pass in the Authorization header of HTTP requests a valid bearer token. It must be obtained via an OpenID client registered in the underlying Gluu Server.
Registering OpenID clients and getting access tokens is out of the scope of this document, but you can check this for a quick start.
To make a method protected, simply add the annotation
org.gluu.casa.rest.ProtectedApi to it.
The following HTTP status codes could arise when using protected methods:
FORBIDDEN (403): This will arise when access was attempted to a protected endpoint but no token was passed.
UNAUTHORIZED (401): The token passed was invalid (it has expired for instance). To handle this, clients of the service should re-request an access token (e.g. with a refresh token), and retry accessing the endpoint.
Casa uses the RESTEasy 3.0 library (an implementation of JAX-RS 2.0 specification) internally. Developers are subject to Jackson 2.0 for JSON content marshalling (classes with
com.fasterxml annotations). The jettison (JAXB) and the Jackson 1.9.x providers are not supported.
Cross domain consumption of services#
When building client-side only applications (HTML+CSS), accessing services located in servers not in the same origin domain can be a big blocker. For these reasons, you can add your origin domain to the set of allowed origins of Casa to overcome the problem. For this, simply do the following:
- Login to Gluu chroot
- Add the domains you want to grant access to, one per line, and then save. For example:
For more information on Cross-Origin Resource Sharing (CORS), visit this page.