Table of Contents
Tigase’s HTTP API component uses the REST module and Groovy scripts responsible for handling and processing incoming HTTP. The end result is Tigase’s REST API. This API may be useful for various integration scenarios.
In these sections we will describe the basic REST endpoints provided by Tigase HTTP API and explain the basics of creating new custom endpoints.
Other endpoints, specific to particular Tigase XMPP Server modules, are described in documentation for the modules providing them.
You may also look at http://localhost:8080/rest/
on your local Tigase XMPP Server installation at HTTP API, which will provide you with basic usage examples for REST endpoints available at your installation.
For more informations about configuration of REST module please see section about the section called “REST module”.
Scripts in the HTTP API component are used for processing all of requests.
To add a new action to the HTTP API component, you will need to create a script written in Groovy for which there will be implementation of class extending tigase.http.rest.Handler
class.
The URI of script will be created from the file’s location of in the scripts folder. For example, if script TestHandler
with regular expression will be set to /test
and will be placed in scripts/rest/tested
, the handler will be called for using the following URI: /rest/tested/test
.
If you are extending classes you will need to set following properties:
/\/()@([^@\/])/
requiredRole
is not null, authentication will be required.HttpServletRequest
to handle incoming content.Extended class should also set closures for one or more of following properties: execGet, execPut, execPost, and execDelete depending on which HTTP action or actions you need to support for the URI. Each closure has a dynamic arguments list. Below is list of arguments passed to closure which describes how and when the list of arguments changes:
callback
closure needs to be called to return data. callback
accepts only one argument of type String,byte[],Map. If data is type of Map it will be encoded to JSON or XML depending of 'Content-Type' header.requiredRole
is not null. In all other cases this argument will not be in arguments list!HttpServletRequest
and it will be instance of HttpServletRequest
of the current HTTP request.decodeContent
is set to false
) it will be an instance of HttpServletRequest
.If property for corresponding HTTP action is not set, then the component will return a 404 HTTP error.
It is possible to gain access to beans managed by Tigase XMPP Server from within groovy script implementing REST handler.
To achieve that implementation of the handler class within groovy script needs to be annotated with @Bean
annotation. In this annotation, you need to pass at least one parameter name
, which should contain desired name of the bean under which this handler will be available within the REST module kernel scope.
With that in place, it is possible to use @Inject
annotation on any field of the Handler
implementation class to tell Tigase Kernel to inject instance of a particular class (or instance of class implementing particular interface).
For more details about Tigase Kernel and beans please check Tigase Kernel
section of the Tigase XMPP Server Development Guide.
Example.
@Bean(name = "test-bean", active = true) class TestHandler extends tigase.http.rest.Handler { @Inject private UserRepository userRepo; // implementation of the handler... }
Please remember that your bean is created and registered within the scope of the REST module kernel. So other beans needs to be accessible there for you to access them.