Setup & Configuration

Tigase’s REST component requires the following in classpath

  • servlet-api-3.1.jar

If you have installed Tigase v7.1.0 or later, the jar is already installed. If you are using an older version of Tigase, you may download the file from this link. Once this is installed, you will also need to add the following lines in your init.properties file to enable the HTTP component.

--comp-name-4=http
--comp-class-4=tigase.http.HttpMessageReceiver

In this default configuration, Tigase will try to start a standalone Jetty HTTP server at port 8080 and start up the default modules, including RestModule which will add context for REST API in the /rest path. RestModule will also load all groovy scripts located in scripts/rest/* directories and will bind them to proper actions for the /rest/* paths.

NOTE: Scripts that handle HTTP requests are available in the component repository in src/scriopts/groovy/tigase/rest/ directory.

Component Properties

Here are some additional properties for the HttpMessageReceiver component that can be set in the init.properties file.

  • {compname}/http/ports[i]= - Sets a comma separated list of ports on which the HTTP server will listen for connections. Default is 8080.
  • {compname}/*********/socket=ssl - Sets the port for SSL connections, replace # with the port number of your choice.
  • {compname}/*********/domain=example.com - This sets the domain name of the SSL certificate from Tigase XMPP certificate store, also sets the port to # to listen for HTTPS connections.
  • {compname}/server-class= - Sets the name of the class used to manage the HTTP server. Currently there are the following options:

    1. tigase.http.JettyStandaloneHttpServer - Starts standalone Jetty HTTP Server instance (requires Tigase HTTP API - Jetty HTTP Server)
    2. tigase.http.jetty.JettyOSGIHttpServer - Uses Jetty HTTP Server instance available as OSGi service (may be used only in OSGi envoirment) (require Tigase HTTP API - Jetty HTTP Server)
    3. tigase.http.java.JavaStandaloneHttpServer - Uses HttpServer provided by Java JDK to start standalone HTTP server (may not work on JDK from every JDK provider).
    4. {compname}/http/threads= - Sets the number of threads available for HTTP component. Default is 4.
    5. {compname}/http/request-timeout= - Sets the timeout time in ms for threads to close on inactive connections. Default is 60 seconds.
Modules

Tigase’s REST Component comes with two modules that can be enabled, disabled, and configured separately. Common settings for modules for component properties are used in the following format: component_name/module_id/module_setting/ the following settings are available for both listed modules:

  • active[B] - Boolean values true/false to enable or disable the module.
  • context-path - Path of HTTP context under which the module should be available.
  • vhosts[s] - Comma separated list of virtual hosts for which the module should be available. If not configured, the module will be available for all vhosts.
Rest Module

This is the Module that provides support for the REST API. Available properties:

  • rest-scripts-dir - Provides ability to specify path to scripts processing REST requests if you do not wish to use default (scripts/rest).
  • api-keys[s] - Comma separated list of strings which would be possible to use as keys to pass api-key parameter to request authorization for request execution. If nothing is passed, then no request will be allowed. To allow any request, this property needs to be set using the following:
http/rest/api-keys[s]=open_access

You may set api-keys to any string you wish, however, when you make requests of the HTTP API service, the included API key must match EXACTLY. Keep the API key to ASCII characters to maintain compatibility. For example, if you were to set the following API key:

http/rest/api-key[s]=a7D2dm3lps138w

Requests made to the HTTP service must conclude with the same key: http://localhost:8080/rest/adhoc/sess-man@domain.com?api-key=a7D2dm3lps138w

dns-webservice

This module provides resolution of DNS names using HTTP protocol. This particular module might be useful for web applications that need to resolve the DNS address to a particular IP. For example to help discover the IP and port of WebSocket services used to connect to the XMPP server.