Topic 5 - Implementing REST PUT and DELETE methods

Introduction

We have already seen how to write GET and POST methods in a Slim web service, and also how to send GET and POST requests from a PHP client. However, you probably remember that REST uses two other methods too: PUT and DELETE. How can we develop code to make use of these methods?

Server side

DELETE request

Handling DELETE requests with a Slim application is easy. We simply write delete and put routes in exactly the same way as we would write get and post routes, by using the delete and put methods of our \Slim\App object. For example:

$app->delete('/flights/{id}', function ($req, $res, array $args) {
    $stmt = $this->db->prepare("DELETE FROM flights WHERE id=?");
    $stmt->bindParam (1, $args["id"]);
    $stmt->execute();
});

This example sets up a DELETE route for the relative URL /flights/{id}, e.g. /flights/45678. If this URL receives a DELETE request, the flight with the corresponding ID will be deleted from the database.

PUT request

With a PUT request, we need to send new data (typically as JSON) to our web service. Our web service then needs to parse that JSON and use it to update the database. Note that calling getBody()->getContents(); on the Request object will retrieve the contents of the body of the HTTP request:

$app->put('/flights/{id}', function ($req, $res, array $args) {
    $put = json_decode($req->getBody()->getContents(), true);
    $stmt = $this->db->prepare("UPDATE flights SET depart=?, arrive=?, price=? WHERE id=?");
    $stmt->execute([$put["depart"], $put["arrive"], $put["price"], $args["id"]]);
});

Note a couple of things about this example:

We use $req->getBody()->getContents() to obtain the body of the request. With a PUT request, this will typically be JSON, so we parse it.
We prepare an UPDATE statement to update the data in the database.
Also note how the PDO execute() now takes a 4-member array. Unless you have come across it yourself, you have not seen this form of execute() before. This array contains all the bound parameters for the prepared statement, i.e. the departure, arrival and price from the JSON and the ID from the URL. This is used instead of four separate bindParam() methods and is much more concise.

Client side

Web services would normally be called from a client script or application, for example with cURL. You have already seen how to use cURL to setup GET and POST requests. You can also use cURL to send a DELETE request by adding the line:

 curl_setopt($curl,CURLOPT_CUSTOMREQUEST, "DELETE");

PUT requests are a bit more difficult as you have to write a temporary file on your server and send that file over to the web service. To easily handle the different types of HTTP request in REST applications, I have written a wrapper function, call_web_service(), with which you can easily make a request to a REST web service. You can download it here (ZIP file); the source code is also viewable online here. To use it in a script, you need to add the line:

include('call_web_service.php');

at the top of your script.

With this script, to call any web service all you need to do is:

$result = call_web_service( URL, method, data);

URL is the URL of the web service;
method is the method (e.g. PUT, DELETE);
data is the data you're sending to the web service. For example if you are using the PUT method to send a request to:
```
http://hittastic.com/song/1009
```
you would send some JSON to update the details of song 1009. This JSON would be parsed in our Slim web service as we saw in the PUT example above.

For example:

DELETE request:
```
$result = call_web_service("https://edward2.solent.ac.uk/~pjones/flight/1009", "DELETE"); 
```
This would send a DELETE request to the URL, causing flight 1009 to be deleted.
PUT request:
```
$newData = [ "depart" => "0900", "arrive" => "1200", "price" => 200.0 ];
$result = call_web_service("https://edward2.solent.ac.uk/~pjones/flight/1009", "PUT", json_encode($newData)); 
```
This would send a PUT request to the URL, causing flight 1009 to be modified. The associative array $newData is encoded into JSON and sent within the body of the request. We then use the method described in "Server side", above, to parse the data sent via the PUT request with Slim.

What does call_web_service() return?

The return value of call_web_service(), $result in the examples above, is an associative array containing the result returned from the web service. It contains two fields:

$result["content"] contains the JSON data returned from the web service;
$result["code"] contains the HTTP code returned from the web service. You can use this to test whether the web service operation was successful or not, and if not, why it wasn't successful.

Exercise

Add a delete route to your web service, to delete a review. The route should handle a URL such as:
```
/review/{id}
```
and delete the review with the given ID.
Add a put route to your web service, to update a review (text, star rating - note that the reviews table now has a star_rating column). JSON containing the new review and star rating should be read by the web service and used to update the review with the ID specified in the URL. Add error handling, so that if the review is blank, or the star rating is not between 1 and 5, an appropriate HTTP code is returned.
Make sure you've done Exercise 3 from Topic 4. On the reviews page, add a link to delete a review. This should link to an additional client_review_delete.php page which sends a DELETE request to the web service and deletes the review.
Add an "Edit Review"