Quick Start Guide

Quick start: From download to first RESTful resource in 5 minutes

Just want to get going? This page is for you! Here we describe all the steps you need to take from download and install to creating your first RESTful resource in just 5 minutes. Each of the steps described here are also discussed in more detail on other pages of this site. Please see our documentation page for all the available information.

Download and install

  1. Download RESTx-0.9.4.tar.gz (if you are using Windows, please see our Windows download and install instructions and then continue with "Create a resource" below).
  2. Unpack and go to the install directory:

    % tar zxvf RESTx-0.9.4.tar.gz
    % cd RESTx-0.9.4

  3. Start the install:

    % ./install.sh

The install script may ask you a few questions and download and install Jython, if necessary. For detailed download and installation guides, please click here.

Start the server

% ./restxctl start

This starts the server in the foreground, with all output on the console. Make sure you can connect with you web-browser to http://localhost:8001.

Create a resource

To demonstrate how we create a resource with RESTx, we use the 'GoogleSearchComponent'; a component, which implements a few lines of code to access Google's search API. GoogleSearchComponent comes with the RESTx distribution and therefore is installed and available in the server by default.

You can find out more about this component by visiting http://localhost:8001/code/GoogleSearchComponent. But to use a component in RESTx, we first need to create a “resource”. A “resource” is the encapsulation of a specific configuration for a given component. For example, to use the Google search API, it is necessary to have a specific Google API key. To complete this example, please first get your Google API key from:  http://code.google.com/apis/ajaxsearch/signup.html, which should only take a minute.

We then create a resource by POSTing the required parameters for a component to the component's URI in JSON encoded form. Specifically, we need to provide a suggested name and the API key as parameter. We can also specify a “default search term” for the search component.

With the browser

For your convenience, RESTx can serve up just the right form for every component. When you have visited the component's URI with your web-browser, you see a '[ Create resource ]' link at the top, above the component description. Click that link and a form is presented to you, displaying the parameters that need to be provided.

In the example of the Google search component, you are asked to specify the name for the new resource (just name it 'TestGoogle' for now), a short description, the Google API key and a default search term, which is optional and can be left empty. Click 'Submit' after you fill in this information. Next you see the resource creation status and the URI of the new resource. You can click on that link and start using the resource.

Voila! You just created your first RESTx resource. It's really that simple.

From the command line

Rather than using the simple form that is supplied by the RESTx server for resource creation, you may at some point be interested to create a resource programmatically or from the command line.

Many different tools can be used to POST information to a URI. To keep it simple, we use the  curlcommand from the command line. Note that the -d @- options at the end of the command line prompts curl to read input from stdin, while the -i option causes output of the response headers received from the server. With -H we can specify our own request headers. Here indicate to the server that we would like the response in JSON, rather than HTML. Make sure to insert your own API key at the appropriate place:

% curl http://localhost:8001/code/GoogleSearchComponent -H "Accept:application/json" -i -d @-
{
   "params" : {                  
      "api_key" : "ABQIA...mZk_A",
      "default_search" : "weather in san francisco”
   },
   "resource_creation_params" : {
      "suggested_name" : "TestGoogle"
   }
}

Just hit CTL-D to end your input. You then see this response from the server:

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 84
Location: /resource/TestGoogle

{
    "name": "TestGoogle",
    "status": "created",
    "uri": "/resource/TestGoogle"
}

In the Location header of the response you see the URI of the newly created resource.

Using the new resource

Now take your web-browser to the new URI, which was just created for us: http://localhost:8001/resource/TestGoogle. You can see some information about the just created resource, including the “services” it provides. A “service”is a sub-resource, which we access to get actual data. You can see nicely formatted search results, if you visit this URI with your browser: http://localhost:8001/resource/TestGoogle/search.

Note that in order to use the resource you do not need to specify the API key with every request. Instead, the API key is stored once by the RESTx server and automatically retrieved when the resource URI is accessed. This showcases nicely how with RESTx it is trivial to create different configurations for components, which are then easily accessed as separate resources.

Whenever you access this resource's URI, you receive Google's results for the default search term. You can override this by specifying a queryparameter on the URI command line, like so:   http://localhost:8001/resource/TestGoogle/search?query=mulesoft.

And there you are: Download, install and your own RESTful resource in  just 5 minutes.

What's next?

Our documentation page holds a lot of useful information. A few highlights you may be interested in: