Chapter 2. REST API
Prev |  | Next

# Chapter 2. REST API

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.

Prev |  | Next
Old Stuff | Home | Usage Examples