RESTful Web Services - part II
Build a RESTful Web Service in Just a Minute - Part 2
This article is the followup to the post Build a RESTful Web Service in Just a Minute, which showed how to build a REST web service which returned a person record from a database.
This article will show you how you can write and deploy another one-minute web service - this one maintains the person table and in subsequent articles we will see AjaxToaster services that handle complex data structures such as you might find in real world applications.
Before we get started it’s assumed that you have AjaxToaster installed and that you have your environment set up (See the resources section for details). It will also be useful if you have created the retrieve service from the first article. (AjaxToaster is an Ajax application server which runs under Tomcat/JBOSS/Glassfish/Websphere - you need an AjaxToaster server to run any of these examples)
Creating the Person maintenance service
To create the service that will update the “person” entity in the database, create a file named “PersonUpdate.xts ” in a directory called ‘contacts’ under the Toaster services directory (If you are running Tomcat on windows this is likely to be found under c:\program files\Tomcat 6.0\webapps\toaster)
e.g
Add the following into PersonUpdate.xts.
update table person using (insert,update)
set personID = {person.id, key:1, uid:true, type:'integer'},
firstname = {person.forename},
lastname = {person.surname},
dob = {person.dateOfBirth};
\g
This script tells AjaxToaster how to save the ‘person’ data into the database. The update statement is similar to a standard SQL update statement, but the phrase “using (insert, update)” means that it can insert OR update data into the ‘person’ database.
Full details of the update syntax can be found in the documentation.
The line “personID = {person.id, key:1, uid:true, type:'integer'},” tells it that personID is the key and that it is defined as an auto-generated key in the database.
If a row is inserted into the database the auto generated key will be populated in the return message.
This statement alone is enough to build the service. It can now be run as a non-restful service with parameters specified in the URL -
e.g.
http://localhost:8080/toaster/contacts/PersonUpdate?inputjson={person:{forename:’Fred’,surname:’Flintstone’,dateOfBirth:’1952-02-02′}}
(see the AjaxToaster parameters documentation for more details)
To turn it into a RESTful service we need to add two new mappings to the “AjaxToaster.urimappings” file. The first mapping is used when person data is being updated (the client application will know the ID of the person) and the second mapping is used when a new person is being created.
/person/{id}.POST=/contacts/PersonUpdate
/person.POST=/contacts/PersonUpdate
And thats it! Now in 7 lines of SQL, 2 lines of config, and zero lines of crazy Java annotations you have a fully operational RESTful service to update and create “person” entities.
If you want to see this service (and the one from the first article) in action then you can download the example code. The file “restful_part2_example.html” uses generic Ajax to invoke the service and POST updates and inserts to it.
Resources
Example code for RESTful Web Services Part II
The example code download includes the toaster.war web application which contains the ajaxToaster server, the html/javascript required to run a basic demo of the personUpdate service, and the “contactsDB.sql” file needed to create the demo database tables.
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 the downloads page. 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!
