It is useful to know what to expect when you are using various HTTP verbs. This is because you can always look into the sent message and verify that the correct HTTP verb was used along with parameters. As an example, have a look at the following message:

GET /WebSearchService/V1/spellingSuggestion?appid=YahooDemo&query=apocalipto HTTP/1.0
Host: search.yahooapis.com:80

It shows that a GET request has been sent to search.yahooapis.com host, requesting for the resource that provides spell suggestion functionality. You can also note the fact that we are using the HTTP 1.0 protocol version here. You will find more information on how to capture the messages and verify the integrity of messages in Chapter 6, Troubleshooting Services and Clients.

Earlier in this chapter it was shown how to access the Yahoo spelling service with the file_get_contents function. The following code shows how to do the same with CURL. As you will notice, the code is a bit lengthier than the equivalent file_get_contents version. Obviously, this is the cost you have to pay in exchange of the customizability of CURL. However, you will soon realize that the increased number of lines is negligible in comparison to what you can do with CURL.

<?php
$url = "http://search.yahooapis.com/WebSearchService/V1/spellingSuggestion?appid=YahooDemo&query=apocalipto";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_GET, true);
curl_exec($ch);
curl_close($ch);
?>

The code shown above would result in a request that looks like the following. (Note that these messages were captured using a message capturing tool, explained in Chapter 6).

GET /WebSearchService/V1/spellingSuggestion?appid=YahooDemo&query=apocalipto HTTP/1.0
Host: search.yahooapis.com:80

And the response:

HTTP/1.1 200 OK
Date: Sat, 17 May 2008 01:24:27 GMT
Cache-Control: private
Connection: close
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:srch" xsi:schemaLocation="urn:yahoo:srch http://api.search.yahoo.com/WebSearchService/V1/WebSearchSpellingResponse.xsd">
<Result>apocalypto</Result>
</ResultSet>

When you run into trouble and want to troubleshoot to figure out what went wrong, looking into the messages to verify the verbs, parameters, HTTP headers and the message content, usually termed payload, would be very helpful. In the following sections, sample source code will be presented to demonstrate how to use CURL API for PHP to make use of various HTTP verbs.

Also, it is worth mentioning that this script would print the response from the service directly to the console, even though we are not using an echo in the script. This is because we need one more option to instruct CURL not to send the received data to the standard output. That option is named CURLOPT_RETURNTRANSFER and must be set to true to get the result of the CURL invocation as a string to a variable. When using CURL for REST clients, more often than not, you would want to capture the return value to a variable rather than printing it directly as an output, because you often would want to process the response from the service before presenting that to the user.

Here is the same client code with option CURLOPT_RETURNTRANSFER set to true. Note that unlike in the previous sample, we now have to use echo to display the returned XML response, and in order to echo we need to capture the response returned as a string from the curl_exec function. Also note that in this sample we are not looking to process the response, rather the output as it is. Later in this chapter we will discuss how to use XML parsers to process the response.

<?php
$url = "http://search.yahooapis.com/WebSearchService/V1/spellingSuggestion?appid=YahooDemo&query=apocalipto";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_GET, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
HTTP GET, CURLusing?>

Most of the services on the internet that support POST or PUT operations would require some form of authentication. This is due to the sensitive nature of these operations especially when it comes to security. The service providers need to control those people who can modify resources.

Because of the complexity of some of the authentication methods in use, if we use a public service to demonstrate the POST method, it would reduce the prominence that should be given to the main subject in discussion in this section of the chapter. Hence, let us use our own service script to see how to use HTTP methods such as POST, PUT and DELETE.

Following is a simple PHP script that you can deploy with your web server and can act as our test service.

<?php
$input = file_get_contents("php://input");
file_put_contents("php://output", $input);
?>

This service script is very simple and straightforward. We just read the incoming payload and write that to the output, a very simple echo service. We will focus on the client side, making requests and processing responses, for the time being, rather than handling requests and generating responses on the server side. We shall visit the server side later. To keep things clean, let's deploy this service to a folder named rest/02 on the web server and you can name this script message_trace.php. To deploy the service, create a directory structure rest/02 in the document root directory of the server and create a PHP script message_service.php in the 02 directory. Copy the PHP script in the previous listing to the message_service.php file.

Now let's see how to write a PHP client that will POST data to this service. This client would send the payload to the service, and the service would echo that payload back. The client would capture the response and echo the response to the output. And here is code for the client.

<?php
$url = 'http://localhost/rest/02/message_trace.php';
$data = <<<XML
<text>Hello World!</text>
XML;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

The output would be:

<text>Hello World!</text>

First, the URL where the service is located is defined. We assume that the server is the localhost, meaning that the service script is hosted on the same machine where the client is hosted.

$url = 'http://localhost/rest/02/message_trace.php';

Then the message content and the payload to be sent to the server is defined.

$data = <<<XML
<text>Hello World!</text>
XML;

Then the initialization and the setting of options for CURL are done.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

Set the option to indicate that we want to make use of HTTP POST verb.

curl_setopt($ch, CURLOPT_POST, true);

Also, set the data to be posted as an option.

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

If you compare this script that POST data from a service to the earlier script where we GET data from a service, you can notice some minor differences.

The rest of the code is similar to the GET client, since we follow the four step process for using CURL.

The semantics of this script is very simple: Prepare the data to be posted, set the HTTP method to be used to POST, set the option pointing to the data to be POSTed, send the request that is POST data, and process the response.

In the REST architectural style, POST is used to update a resource and the response might not contain any payload. However, some applications could choose to return the old resource value in the response after updating the resource with new incoming data.

As in the case of the example used to demonstrate HTTP POST method, we will use a simple demo service for demonstrating HTTP PUT method, to keep our focus on how to use CURL to make a PUT request. Here is the code for service script, and we will name this script as put.php.

<?php
$putdata = fopen("php://input", "r");
$fp = fopen("put_data_file.txt", "a");
while ($data = fread($putdata, 1024))
fwrite($fp, $data);
fclose($fp);
fclose($putdata);
?>

This simple script will open the input stream containing the PUT data as a file. A file, when read from start to end could be considered as a stream of data. A file could be opened and its data read, and that data could be considered as an input for a script. Since this mechanism provides the input as a stream of data, it is often termed as the input stream. Similarly, a file could be opened and the output be written to that file, then we call it the output stream. After reading the input stream, this script then opens another file named put_data_file.txt and places all the data PUT into that file. Lets host this service in the folder rest/02.

Note that, even though in theory we could create a new resource with HTTP PUT method with REST architectural style, most of the web servers will not allow the creation of new resources on the server due to security reasons. Since PHP is often hosted as a module of the web server, the file write privileges the PHP script has would be similar to those of the web server. Web servers discourage the Web application users by allowing them to place content into the web server host's file system, because such facilities could be misused to upload harmful scripts and compromise the host machine's security by executing those uploaded scripts.

<?php
$url = 'http://localhost/rest/02/put.php';
$fh = fopen('data.txt', 'r'),
$data = file_get_contents('data.txt'),
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_PUT, true);
curl_setopt($ch, CURLOPT_INFILE, $fh);
curl_setopt($ch, CURLOPT_INFILESIZE, strlen($data));
curl_exec($ch);
curl_close($ch);
?>

To run the previous PHP script, create an input text file data.txt, which has some text data in the document root directory of the server.

Note that there is no output generated by this example script. This is because the script uses the functionality provided by the script that it is accessing, namely put.php, the service in this case, and there is no response message involved with this interaction. When working with services and clients, it is a common scenario to have no visible output associated with the client and server interactions. The client would trigger some business processing on the server side, and the service would consume the request and do the needful backend processing, and would not have anything to return to the client.

You can see from this source, the PUT script is very similar to the POST script, except for a few differences. One trivial change from POST to PUT is that the option CURLOPT_PUT instead of CURLOPT_POST has been used. Also, unlike in the POST case, where we set the post data using CURLOPT_POSTFIELDS option, we have set the CURLOPT_INFILE and CURLOPT_INFILESIZE options to provide the name of the file and the size of the data in the file to be PUT.

HTTP DELETE verb is also a sensitive verb like HTTP PUT. This is because the verb can be used to delete a resource, and deleting an existing resource requires proper access privileges. For demonstration purposes, we will use the same service script that we used for PUT operation and see how CURL API can be used to invoke HTTP DELETE. Here is the source code.

<?php
$url = 'http://localhost/rest/02/put.php';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_exec($ch);
curl_close($ch);
?>

As you may notice, unlike the POST or PUT requests, there is no dedicated option in CURL for delete. Rather you have to use the CURLOPT_CUSTOMREQUEST option with the value DELETE to use the DELETE verb. Also note that, in this simple example, when the put.php script received the DELETE request, the script would simply ignore the request, and leave the data file content as it is. Alternatively, the service script could have erased the data file.

unlink("put_data_file.txt");

One of the common uses of the HTTP DELETE operation is to end the life of a resource, as we discussed in the last chapter. As an example, you could delete a database entry mapped to a resource after receiving a DELETE request. We will see this later in this book, in Chapter 4 where we will discuss a real world sample application.