Features > RESTful API

What is it?

The REST API provides the means for exporting Agilefant's data to some other service or application by making requests. See http://en.wikipedia.org/wiki/Representational_State_Transfer for further information.

Turning it on

The remote API is switched off by default. It can be enabled in Tomcat's setting files, namely server.xml and *-users.xml. Below are samples of the two files with unnecessary parts left out from server.xml.

Steps:

1. Open up TOMCAT_HOME/conf/server.xml
2. Insert the Resource description inside the <GlobalNamingResources> element
3. Define the <Context> for the application
   1. See http://tomcat.apache.org/tomcat-5.5-doc/config/context.html for more
4. Inside the Context, define the environment variable 'remoteEnabled' and the user realm for the context as shown
5. Create the file TOMCAT_HOME/conf/agilefant-users.xml
6. Insert the contents from the sample file
   1. Change the password
7. Restart Tomcat and go to http://path/to/your/agilefant/rs/application.wadl
   1. The application should ask for credentials. Insert the ones defined in agilefant-users.xml
   2. You should be able to log in. The response is an XML file with Agilefant's WADL-description

If you have multiple Agilefant applications running on the same Tomcat application server it is highly recommended to create a separate user database for each instance.

You may want to secure the whole remote API by using for example Apache HTTPD as a proxy and deny access to the api for any other than trusted services.

<GlobalNamingResources>
...
    <!-- Use agilefantrs-users.xml as the base for usernames and passwords for 'AgilefantRSUserDatabase' -->
    <Resource auth="Container" description="User database for Agilefant remote"
        factory="org.apache.catalina.users.MemoryUserDatabaseFactory" name="AgilefantRSUserDatabase"
        pathname="conf/agilefant-users.xml" type="org.apache.catalina.UserDatabase"/>
...
</GlobalNamingResources>
...
<Host appBase="webapps" ...>
  <!-- One Context per Agilefant instance -->
  <Context path="/agilefant" docBase="agilefant">
    <!-- User the 'AgilefantRSUserDatabase' as the realm for Agilefant -->
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="AgilefantRSUserDatabase"/>

    <!-- Enable the REST interface -->
    <Environment name="remoteEnabled" value="true" type="java.lang.Boolean" override="false"/>
  </Context>
</Host>
...

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="agilefantremote"/>
  <user username="agilefant" password="agilefant" roles="agilefantremote"/>
</tomcat-users>

Sample application

There is a sample application, which uses the RESTful API to get data out of Agilefant. Download the sample application with svn.

> svn co http://www.agilefant.org/svn/agilefantmodules/reporting/trunk reporting

Browse in to the folder and run the program. You need to have Apache Maven installed to run the application. Find the file reporting/src/main/resources/remote.properties, and change the username, password and remote api url to match those of your Agilefant instance (see previous).

Run the application:

> mvn jetty:run

The application starts by default to http://localhost:8090/. If you want to change the addresss, modify the project's pom.xml.

How does it work?

The application uses the same username and password as the Agilefant instance it connects to. This is done by sending a REST request to authenticate. If the credentials are correct, Agilefant returns the user as XML. If they're not correct, Agilefant sends HTTP status 412.

Look through the fi.hut.soberit.agilefant.reporting.controller package to see, how requests through Jersey are made. Jersey does the XML unmarshalling automatically, when it has the agilefant-model.jar.

Developing your own plugins

We provide a maven archetype, which you can use to easily create your own applications that use Agilefant's RESTful API. Select the RemoteSkeleton archetype.

mvn archetype:generate -DarchetypeCatalog=http://www.agilefant.org/maven/archetype-catalog.xml

The application uses Jersey client to consume the RESTful services, and has the basic authentication mechanism.