RESTful Web Services in Just a Minute
Build a RESTful Web Service in Just a Minute
This article will show you how you can write and deploy a RESTful web service (that does something useful!) in around a minute.
It is planned to be the first part in a series of articles that will use AjaxToaster to demonstrate RESTful web services interacting with a relational database. In this first article we will show you a service that retrieves a simple data structure, in subsequent articles we will move onto a service that updates data and then services that handle complex data structures such as you might find in real world applications.
Before we start the stopwatch :-), it’s assumed that you have AjaxToaster installed in your environment and that you have our fictitious “contacts” database set-up. For instructions on how to do this, use the links in the resources section at the end of the article.
Ready, steady, go!!!
First you should create a new directory named “contacts ” in the toaster web applications’ “services” directory. On a standard Windows installation of Tomcat 6.0 this directory will be “C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\toaster\services”. This is where we will create our web services.
Create a file named “service.config ” in your new directory and add the following content.
The content of this file sets the default database for all service script files in the directory. We are assuming that the ‘mydb’ database connection has been setup as described in the resources section.
Now create a file in the ‘contacts’ directory called “PersonService.stx ” with the following content:
xmlselect using noschema
select
personid into xml:{person.id},
firstname into xml:{person.forename},
lastname into xml:{person.surname},
dob into xml:{person.dateOfBirth}
from
person
where
personId = ${PERSONID}
order by
personid;
Now edit the “AjaxToaster.urimappings ” file (which is in the “services” directory) and add the following line to define your RESTful URI:
/person/{id}.GET=/contacts/PersonService?PERSONID={id}
When a client accesses a URI in the format “…/person/999” using an HTTP GET, the “PersonService.stx” script will be invoked and passed 999 as the “PERSONID” parameter. This will run the query above against the database and return person number 999 to you.
So that’s it! You are now ready to use your new RESTful web service. Point your web browser at a URL such as http://localhost:8080/toaster/person/1 and you should see the person data as shown below.
You can change the ‘person’ that you retrieve simply by changing the number on the end of the URL (use 1 through 5 for the person records that are setup by the database creation script).
The client can also decide to receive the data as a JSON message by either adding a parameter to the URL called “returnjson” (for example http://localhost:8080/toaster/person/1?returnjson) or by setting the HTTP request header “Accept ” to “text/json “.
In the next article we will look at how the client can set the HTTP request header and how we can update data in the database using AjaxToaster RESTful web services.
Resources
Java Runtime
AjaxToaster requires Java 5 or later. This can be downloaded from the
Sun website.
Java Web Container
Any Java web container is able to run AjaxToaster, but if you are getting started then we recommend using Apache Tomcat 6. This can be downloaded from here and you can find documentation on setting it up here .
AjaxToaster
The AjaxToaster application can be downloaded from here. The “toaster.war” file is the only one you need for this article, but “toasterExamples.war” is an application that contains lots of useful documentation and example applications. We also recommend that you read the release notes which contain information on features of AjaxToaster.
For instructions on how to install a WAR file under Apache Tomcat use the following links;
MySQL Database
The script that sets up the “contacts” database used in this series of articles has been developed against a MySQL database. MySQL can be downloaded from here .
Creating the Database Tables
The script that creates the database, tables and data can be downloaded here (contactsDB.sql). By default the script will create a database named ‘mydb ‘. If you edit the script to change this then you must also change the name of the database used in the JDBC URL in the “AjaxToaster.properties” file.
JDBC Driver
The JDBC driver for MySQL can be downloaded from mysql.com.
To make the JDBC driver accessible to AjaxToaster you should copy the downloaded JAR file to the “WEB-INF” directory of the “toaster” application installed under Tomcat.
Connecting AjaxToaster to the Database
To make AjaxToaster aware of the database you must add the following lines to the “AjaxToaster.properties” file in the “toaster” web applications’ “services” directory.
jdbc.database.mydb=jdbc:mysql://localhost/mydb
jdbc.username.mydb=username
jdbc.password.mydb=password
Change mydb, username, and password to suite your local database.
AjaxToaster Note
AjaxToaster will automatically detect changes that you make to the configuration and web service script files. However, this checking is done every 30 seconds by default, so, if you are too fast, you might find that AjaxToaster has not noticed your shiny new RESTful web service when you first try to access it!
October 16th, 2008 at 11:45 am
[…] For how to create REST webservices take a look at: http://inverse2.com/?p=43 Possibly related posts: (automatically generated)Base64 : Converting Binary Data to ASCII […]