Give it a REST

Play with our RESTful database interface with our interactive REST tutorial

Welcome

What is all this REST talk about? Now you can find out for yourself by playing with our interactive REST tutorial that runs right in your Web browser.

On this site you will find a RESTful interface (written in PHP) to a database (a MySQL database, but that's not important). Below you will find a interactive tutorial that will get you accessing, adding and deleting rows from our database via our Javascript powered REST browser.

Open the Javascript REST Browser →

The browser opens to the right and will always stick with you as you scroll through this tutorial.

GETting started

REST starts with a HTTP GET request to the root URL of the service, so point your browser at /tutorial to get started.

You will be prompted for a username and password via HTTP Authentication, these are the MySQL username and password to connect to the database server with. These details will be passed in plain text over the wire, standard SSL can be used to encrypt the HTTP connection and protect the username and password.

Enter the username p126371rw and password demo to access the URL.

<database>
	<table xlink:href="/tutorial/company">company</table>
	<table xlink:href="/tutorial/user">user</table>
</database>

Listing 1

You should receive an XML file like Listing 1 (although you may get a HTML file depending on the Accept headers your browser sends, you can access /tutorial.xml to specifically get XML, or /tutorial.html to explicitly get HTML).

One of the secrets of REST is that to co-ordinate communications, both parties need to share an understanding of the representation formats passed back and forth. So in this case, we're presuming that we understand what these XML documents mean.

For this simple interface it's easy, the XML shows that our database has two tables ("company" and "user") which are accessable at the given URLs (/tutorial/company and /tutorial/user respectively).

<table>
	<row xlink:href="/tutorial/user/1">1</row>
	<row xlink:href="/tutorial/user/2">2</row>
</table>

Listing 2

GETting /tutorial/user will then give you an XML file like Listing 2. This shows that the "user" table contains 2 rows, indexed 1 and 2.

<row>
	<uid>1</uid>
	<firstname>Joe</firstname>
	<surname>Everyone</surname>
	<email>joe.everyone@example.org</email>
	<company_uid xlink:href="/tutorial/company/1">1</company_uid>
</row>

Listing 3

Finally GETting /tutorial/user/1 will then give you an XML file like Listing 3 showing all the data in that row.

As you can see, we've just navigated through the database in the same way you'd navigate through a Web site, using hypertext to move from one resource to another.

That's it for GETting information from the REST interface, we're used to getting information from the Web, it's nothing new or clever, so lets move on. The rest of the tutorial covers the more complex task of the other 3 HTTP methods.

Inserting a row (PUT and POST)

Again, to update information we presume that both sides understand an agreed upon format. In this case, URL-encoded name/value pairs. We also know which HTTP methods to use since they are standard and are always used in the same way.

There are two ways to add a row to a table:

Using a PUT method we can write a resource to a specific URL, but to do this we must already know the primary key we want to insert it at (since the primary key forms part of the URL). The PUT method should be used to create or overwrite a known named resource.
Using a POST method we can send a rows representation to a tables URL and get it to append it to itself. The POST method should be used to create a brand new resource as a sub-resource of a collection (and when you want the server to make up the URL for you).

We'll look at these cases in turn.

PUT

To put a new row to a table we have to send a complete representation of the row to the server, we do this as a series of field=value pairs.

For example, to insert a new row into our user table we need to craft a HTTP PUT request containing values for uid, firstname, surname, email, company_uid:

PUT /tutorial/user/4 HTTP/1.1

firstname=Jim
surname=Example
email=jim@example.org
company_uid=1

Listing 4

Listing 4 shows the required HTTP PUT request. Things to notice about this are:

The document content consists of new line seperated field=value pairs, which should be URL encoded where necessary.
The primary key of the item to add is not present in the document body, but the request is sent to the new URL for the row which includes the primary key.

Give it a try now, make sure you use a uid that doesn't already exist, if .

HTTP/1.x 201 Created

Listing 5

If all goes well, the HTTP response we should recieve is shown in Listing 5. No document data will be returned, use the main LiveHTTPHeaders window to see your response headers.

A 201 Created header means that the resource was created okay, if you now issue a GET on /tutorial/user you will see the new user added to the database table.

If a user with the same uid already existed, then you would have just updated it with your new data.

POST

The POST request is the same as the PUT request except that we issue it to the URL of the table and not a specific row.

POST /tutorial/user HTTP/1.1

firstname=Jim
surname=Example
email=jim@example.org
company_uid=1

Listing 6

Listing 6 shows the required HTTP POST request. It uses the same request body as the PUT request but is issued to the tables URL.

HTTP/1.x 201 Created
Location: /tutorial/user/4

Listing 7

If all goes well, the HTTP response we should recieve is shown in Listing 7. You'll notice that the server returns a location header that points us to the newly created resource.

Updating a row

Updating a row is the same as adding a new row with a known uid, simply PUT the new data to the rows URL.

REST makes no distinction between creating a named resource and updating an existing resource. Both operations have the same outcome, the data associated with the resource is stored on the server at the given URL whether the resource existed beforehand or not.

DELETE

To delete a row, a HTTP DELETE request should be sent to the URL of the row to remove.

DELETE /tutorial/user/4 HTTP/1.1

Listing 8

If successful, you should recieve a 204 response. If you now issue a GET on /tutorial/user/4 you should get a 404 Not Found error.

The end

That's it. However, the code that powers the tutorial (called PHPRESTSQL, quite a monster acronym I know) is available to download and try out for yourself. Give it a try...