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.
The browser opens to the right and will always stick with you as you scroll through this tutorial.
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>
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.
<table> <row xlink:href="/tutorial/user/1">1</row> <row xlink:href="/tutorial/user/2">2</row> </table>
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>email@example.com</email> <company_uid xlink:href="/tutorial/company/1">1</company_uid> </row>
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.
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:
We'll look at these cases in turn.
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 firstname.lastname@example.org company_uid=1
Listing 4 shows the required HTTP PUT request. Things to notice about this are:
Give it a try now, make sure you use a uid that doesn't already exist, if .
HTTP/1.x 201 Created
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.
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@example.com company_uid=1
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
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 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.
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
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.
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...