Chapter 2. REST API

Table of Contents

Scripting introduction
Properties
Properties containing closures
Accessing beans
Usage Examples
Retrieving user avatar
Retrieving list of available adhoc commands
Retrieving command form
Executing example ad-hoc commands
Operations on VHosts/Domains
Sending any XMPP Stanza
Setting XMPP user status
BOSH HTTP Pre-Binding
Bosh (HTTP) Pre-Binding
Configuration

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 ???.

Scripting introduction

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.

Properties

If you are extending classes you will need to set following properties:

  • regex - Regular expression which is used to match the request URI and parse parameters embedded in the URI. For example: /\/()@([^@\/])/
  • requiredRole - Required role of user in order to be able to access this URI. Available values are: null, "user", and "admin". If requiredRole is not null, authentication will be required.
  • isAsync - If set to true, it will be possible to wait for results, for example waiting for an response IQ stanza.
  • decodeContent - If set to false, then content of the request will not be parsed and your script will receive instance of HttpServletRequest to handle incoming content.

Properties containing closures

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:

  1. service - Implementation of Service interface. This is used to access the server database or send/receive XMPP stanzas.
  2. callback - The 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.
  3. user - Will be passed only if requiredRole is not null. In all other cases this argument will not be in arguments list!
  4. request - Will be passed only if declared as instance of HttpServletRequest and it will be instance of HttpServletRequest of the current HTTP request.
  5. content - Parsed content of request. This closure will not be in arguments list if Content-Length of request is empty. If Content-Type is XML or JSON returned as Map, otherwise (or if decodeContent is set to false) it will be an instance of HttpServletRequest.
  6. x - Additional arguments passed to callback are groups from regular expression matching the URI. Groups are not passed as a list, but are added to list of arguments as next arguments.

If property for corresponding HTTP action is not set, then the component will return a 404 HTTP error.

Accessing beans

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...
}

Warning

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.