c



 



One of the latest (sort of) crazes sweeping the net is APIs, more specifically those that leverage REST. It¶s really no surprise either, as consuming REST
APIs is so incredibly easy« in any language. It¶s also incredibly easy to create them as you essentially use nothing more than an HTTP spec that has
existed for ages. One of the few things that I give Rails credit for is its well thought-out REST support, both for providing and consuming these APIs (as
its been explained by all the Rails fanboys I work with).

Seriously, if you¶ve never used REST, but you¶ve ever had to work with (or worse, create) a SOAP API, or simply opened a WSDL and had your head
explode, boy do I have good news for you!

  c


Before we get into writing some code, I want to make sure everyone¶s got a good understanding of what REST is and how its great for APIs. First,
technically speaking, REST isn¶t specific to just APIs, it¶s more of a generic concept. However, obviously, for the sake of this article we¶ll be talking about
it in the context of an API. So, let¶s look at the basic needs of an API and how REST addresses them.




All APIs need to accept requests. Typically, with a RESTful API, you¶ll have a well-defined URL scheme. Let¶s say you want to provide an API for users
on your site (I know, I always use the ³users´ concept for my examples). Well, your URL structure would probably be something like, ³api/users´ and
³api/users/[id]´ depending on the type of operation being requested against your API. You also need to consider how you want to accept data. These
days a lot of people are using JSON or XML, and I personally prefer JSON because it works well with JavaScript, and PHP has easy functionality for
encoding and decoding it. If you wanted your API to be really robust, you could accept both by sniffing out the content-type of the request (i.e.
application/json or application/xml), but it¶s perfectly acceptable to restrict things to one content type. Heck, you could even use simple key/value pairs if
you wanted.

The other piece of a request is what it¶s actually meant to do, such as load, save, etc. Normally, you¶d have to come up with some sort of architecture
that defines what action the requester (consumer) desires, but REST simplifies that. By using HTTP request methods, or verbs, we don¶t need to define
anything. We can just use the GET, POST, PUT, and DELETE methods, and that covers every request we¶d need. You can equate the verbs to your
standard crud-style stuff: GET = load/retrieve, POST = create, PUT = update, DELETE = well, delete. It¶s important to note that these verbs don¶t directly
translate to CRUD, but it is a good way to think about them. So, going back to the above URL examples, let¶s take a look at what some possible
requests could mean:

˜ Ë

 
 ± List all users

˜ Ë

 
 ± List info for user with ID of 1
˜


 
 ± Create a new user
˜


 
 ± Update user with ID of 1
˜ h!

 
 ± Delete user with ID of 1

As you hopefully see, REST has already taken care of a lot of the major headaches of creating your own API through some simple, well-understood
standards and protocols, but there¶s one other piece to a good API«




So, REST handles requests very easily, but it also makes generating responses easy. Similar to requests, there are two main components of a RESTful
response: the response body, and a status code. The response body is pretty easy to deal with. Like requests, most responses in REST are usually
either JSON or XML (perhaps just plain text in the case of POSTs, but we¶ll cover that later). And, like requests, the consumer can specify the response
type they¶d like through another part of the HTTP request spec, ³Accept´. If a consumer wishes to receive an XML response, they¶d just send an Accept
header as a part of their request saying as much (´Accept: application/xml´). Admittedly, this method isn¶t as widely adopted (tho it should be), so you
have can also use the concept of an extension in the URL. For example, /api/users.xml means the consumer wants XML as a response, similarly
/api/users.json means JSON (same for things like /api/users/1.json/xml). Either way you choose (I say do both), you should pick a default response type
as a lot of the time people wont¶ even tell you what they want. Again, I¶d say go with JSON. So, no Accept header or extension (i.e. /api/users) should
not fail, it should just fail-over to the default response-type.

But what about errors and other important status messages associated with requests? Easy, use HTTP status codes! This is far and above one of my
favorite things about creating RESTful APIs. By using HTTP status codes, you don¶t need to come up with a error / success scheme for your API, it¶s
already done for you. For example, if a consumer POSTS to /api/users and you want to report back a successful creation, simply send a 201 status code
(201 = Created). If it failed, send a 500 if it failed on your end (500 = Internal Server Error), or perhaps a 400 if they screwed up (400 = Bad request).
Maybe they¶re trying to POST against an API endpoint that doesn¶t accept posts« send a 501 (Not implemented). Perhaps your MySQL server is down,
so your API is temporarily borked« send a 503 (Service unavailable). Hopefully, you get the idea. If you¶d like to read up a bit on status codes, check
them out on wikipedia: List of HTTP Status Codes.

I¶m hoping you see all the advantages you get by leveraging the concepts of REST for your APIs. It really is super-cool, and its a shame its not more
widely talked about in the PHP community (at least as far as I can tell). I think this is likely due to the lack of good documentation on how to deal with
requests that aren¶t GET or POST, namely PUT and DELETE. Admittedly, it is a bit goofy dealing with these, but it certainly isn¶t hard. I¶m also sure
some of the popular frameworks out there probably have some sort of REST implementation, but I¶m not a huge framework fan (for a lot of reasons that I
won¶t get into), and it¶s also good to know these things even if somebody¶s already created the solution for you.

If you¶re still not convinced that this is a useful API paradigm, take a look at what REST has done for Ruby on Rails. One of its major claims to fame is
how easy it is to create APIs (through some sort of RoR voodoo, I¶m sure), and rightly so. Granted I know very little about RoR, but the fanboys around
the office have preached this point to me many times. But, I digress« let¶s write some code!
Ë
 " 
 



One last disclaimer: the code we¶re about to go over is in no way intended to be used as an example of a robust solution. My main goal here is to show
how to deal with the individual components of REST in PHP, and leave creating the final solution up to you.

So, let¶s dig in! I think the best way to do something practical is to create a class that will provide all the utility functions we need to create a REST API.
We¶ll also create a small class for storing our data. You could also then take this, extend it, and apply it to your own needs. So, let¶s stub some stuff out:

class RestUtils{
public static function processRequest()
{

public static function sendResponse($status = 200, $body = '', $content_type = 'text/html')

{

public static function getStatusCodeMessage($status)

{
// these could be stored in a .ini file and loaded
// via parse_ini_file()... however, this will suffice
// for an example
$codes = Array(
100 => 'Continue',
101 => 'Switching Protocols',
200 => 'OK',
201 => 'Created',
202 => 'Accepted',
203 => 'Non-Authoritative Information',
204 => 'No Content',
205 => 'Reset Content',
206 => 'Partial Content',
300 => 'Multiple Choices',
301 => 'Moved Permanently',
302 => 'Found',
303 => 'See Other',
304 => 'Not Modified',
305 => 'Use Proxy',
306 => '(Unused)',
307 => 'Temporary Redirect',
400 => 'Bad Request',
401 => 'Unauthorized',
402 => 'Payment Required',
403 => 'Forbidden',
404 => 'Not Found',
405 => 'Method Not Allowed',
406 => 'Not Acceptable',
407 => 'Proxy Authentication Required',
408 => 'Request Timeout',
409 => 'Conflict',
410 => 'Gone',
411 => 'Length Required',
412 => 'Precondition Failed',
413 => 'Request Entity Too Large',
414 => 'Request-URI Too Long',
415 => 'Unsupported Media Type',
416 => 'Requested Range Not Satisfiable',
417 => 'Expectation Failed',
500 => 'Internal Server Error',
501 => 'Not Implemented',
502 => 'Bad Gateway',
503 => 'Service Unavailable',
504 => 'Gateway Timeout',
505 => 'HTTP Version Not Supported'
);

return (isset($codes[$status])) ? $codes[$status] : '';

}
}

class RestRequest
{
private $request_vars;
 private $data;
private $http_accept;
private $method;

public function __construct()

{
$this->request_vars = array();
$this->data = '';
$this->http_accept = (strpos($_SERVER['HTTP_ACCEPT'], 'json')) ? 'json' : 'xml';
$this->method = 'get';
}

public function setData($data)

{
$this->data = $data;
}

public function setMethod($method)

{
$this->method = $method;
}

public function setRequestVars($request_vars)

{
$this->request_vars = $request_vars;
}

public function getData()

{
return $this->data;
}

public function getMethod()

{
return $this->method;
}

public function getHttpAccept()

{
return $this->http_accept;
}

public function getRequestVars()

{
return $this->request_vars;
}
}

OK, so what we¶ve got is a simple class for storing some information about our request (RestRequest), and a class with some static functions we can
use to deal with requests and responses. As you can see, we really only have two functions to write« which is the beauty of this whole thing! Right, let¶s
move on«

#
 "




Processing the request is pretty straight-forward, but this is where we can run into a few catches (namely with PUT and DELETE« mostly PUT). We¶ll
go over those in a moment, but let¶s examine the RestRequest class a bit. If you¶ll look at the constructor, you¶ll see that we¶re already interpreting the
HTTP_ACCEPT header, and defaulting to JSON if none is provided. With that out of the way, we need only deal with the incoming data.

There are a few ways we could go about doing this, but let¶s just assume that we¶ll always get a key/value pair in our request: µdata¶ => actual data. Let¶s
also assume that the actual data will be JSON. As stated in my previous explanation of REST, you could look at the content-type of the request and deal
with either JSON or XML, but let¶s keep it simple for now. So, our process request function will end up looking something like this:

public static function processRequest()

{
// get our verb
$request_method = strtolower($_SERVER['REQUEST_METHOD']);
$return_obj = new RestRequest();
// we'll store our data here
$data = array();

switch ($request_method)
{
// gets are easy...
case 'get':
 $data = $_GET;
break;
// so are posts
case 'post':
$data = $_POST;
break;
// here's the tricky bit...
case 'put':
// basically, we read a string from PHP's special input location,
// and then parse it out into an array via parse_str... per the PHP docs:
// Parses str as if it were the query string passed via a URL and sets
// variables in the current scope.
parse_str(file_get_contents('php://input'), $put_vars);
$data = $put_vars;
break;
}

// store the method

$return_obj->setMethod($request_method);

// set the raw data, so we can access it if needed (there may be

// other pieces to your requests)
$return_obj->setRequestVars($data);

if(isset($data['data']))
{
// translate the JSON to an Object for use however you want
$return_obj->setData(json_decode($data['data']));
}
return $return_obj;
}

Like I said, pretty straight-forward. However, a few things to note« First, you typically don¶t accept data for DELETE requests, so we don¶t have a case
for them in the switch. Second, you¶ll notice that we store both the request variables, and the parsed JSON data. This is useful as you may have other
stuff as a part of your request (say an API key or something) that isn¶t truly the data itself (like a new user¶s name, email, etc.).

So, how would we use this? Let¶s go back to the user example. Assuming you¶ve routed your request to the correct controller for users, we could have
some code like this:

$data = RestUtils::processRequest();

switch($data->getMethod)
{
case 'get':
// retrieve a list of users
break;
case 'post':
$user = new User();
$user->setFirstName($data->getData()->first_name); // just for example, this should be done cleaner
// and so on...
$user->save();
break;
// etc, etc, etc...
}

Please don¶t do this in a real app, this is just a quick-and-dirty example. You¶d want to wrap this up in a nice control structure with everything abstracted
properly, but this should help you get an idea of how to use this stuff. But I digress, let¶s move on to sending a response.


 "




Now that we can interpret the request, let¶s move on to sending the response. We already know that all we really need to do is send the correct status
code, and maybe some body (if this were a GET request, for example), but there is an important catch to responses that have no body. Say somebody
made a request against our sample user API for a user that doesn¶t exist (i.e. api/user/123). The appropriate status code to send is a 404 in this case,
but simply sending the status code in the headers isn¶t enough. If you viewed that page in your web browser, you would get a blank screen. This is
because Apache (or whatever your web server runs on) isn¶t sending the status code, so there¶s no status page. We¶ll need to take this into account
when we build out our function. Keeping all that in mind, here¶s what the code should look like:

public static function sendResponse($status = 200, $body = '', $content_type = 'text/html')

{
$status_header = 'HTTP/1.1 ' . $status . ' ' . RestUtils::getStatusCodeMessage($status);
// set the status
header($status_header);
 // set the content type
header('Content-type: ' . $content_type);

// pages with body are easy

if($body != '')
{
// send the body
echo $body;
exit;
}
// we need to create the body if none is passed
else
{
// create some body messages
$message = '';

// this is purely optional, but makes the pages a little nicer to read
// for your users. Since you won't likely send a lot of different status codes,
// this also shouldn't be too ponderous to maintain
switch($status)
{
case 401:
$message = 'You must be authorized to view this page.';
break;
case 404:
$message = 'The requested URL ' . $_SERVER['REQUEST_URI'] . ' was not found.';
break;
case 500:
$message = 'The server encountered an error processing your request.';
break;
case 501:
$message = 'The requested method is not implemented.';
break;
}

// servers don't always have a signature turned on (this is an apache directive "ServerSignature On")
$signature = ($_SERVER['SERVER_SIGNATURE'] == '') ? $_SERVER['SERVER_SOFTWARE'] .
' Server at ' . $_SERVER['SERVER_NAME'] . ' Port ' . $_SERVER['SERVER_PORT'] : $_SERVER['SERVER_SIGNATURE'];

// this should be templatized in a real-world solution

$body = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>' . $status . ' ' . RestUtils::getStatusCodeMessage($status) . '</title>
</head>
<body>
<h1>' . RestUtils::getStatusCodeMessage($status) . '</h1>
<p>' . $message . '</p>
<hr />
<address>' . $signature . '</address>
</body>
</html>';

echo $body;
exit;
}
}

That¶s It! We technically have everything we need now to process requests and send responses. Let¶s talk a bit more about why we need to have a
standard body response or a custom one. For GET requests, this is pretty obvious, we need to send XML / JSON content instead of a status page
(provided the request was valid). However, there¶s also POSTs to deal with. Inside of your apps, when you create a new entity, you probably fetch the
new entity¶s ID via something like mysql_insert_id(). Well, if a user posts to your API, they¶ll probably want that new ID as well. What I¶ll usually do in this
case is simply send the new ID as the body (with a 201 status code), but you could also wrap that in XML or JSON if you¶d like.

So, let¶s extend our sample implementation a bit:

switch($data->getMethod)
{
// this is a request for all users, not one in particular
case 'get':
$user_list = getUserList(); // assume this returns an array

if($data->getHttpAccept == 'json')
{
 RestUtils::sendResponse(200, json_encode($user_list), 'application/json');
}
else if ($data->getHttpAccept == 'xml')
{
// using the XML_SERIALIZER Pear Package
$options = array
(
'indent' => ' ',
'addDecl' => false,
'rootName' => $fc->getAction(),
XML_SERIALIZER_OPTION_RETURN_RESULT => true
);
$serializer = new XML_Serializer($options);

RestUtils::sendResponse(200, $serializer->serialize($user_list), 'application/xml');

}

break;
// new user create
case 'post':
$user = new User();
$user->setFirstName($data->getData()->first_name); // just for example, this should be done cleaner
// and so on...
$user->save();

// just send the new ID as the body

RestUtils::sendResponse(201, $user->getId());
break;
}

Again, this is just an example, but it does show off (I think, at least) how little effort it takes to implement RESTful stuff.

  " 

So, that¶s about it. I¶m pretty confident that I¶ve beaten the point that this should be quite easy into the ground, so I¶d like to close with how you can take
this stuff further and perhaps properly implement it.

In a real-world MVC application, what you would probably want to do is set up a controller for your API that loads individual API controllers. For example,
using the above stuff, we¶d possibly create a UserRestController which had four methods: get(), put(), post(), and delete(). The API controller would look
at the request and determine which method to invoke on that controller. That method would then use the utils to process the request, do what it needs to
do data-wise, then use the utils to send a response.

You could also take it a step further than that, and abstract out your API controller and data models a bit more. Rather than explicitly creating a controller
for every data model in your app, you could add some logic into your API controller to first look for an explicitly defined controller, and if none is found, try
to look for an existing model. For example, the url ³api/user/1Ǝ, would first trigger a lookup for a ³user´ rest controller. If none is found, it could then look
for a model called ³user´ in your app. If one is found, you could write up a bit of automated voodoo to automatically process all the requests against
those models.

Going even further, you could then make a generic ³list-all´ method that works similar to the previous paragraph¶s example. Say your url was ³api/users´.
The API controller could first check for a ³users´ rest controller, and if none was found, recognize that users is pluaralized, depluralize it, and then look
for a ³user´ model. If one¶s found, load a list the list of users and send that off.

Finally, you could add digest authentication to your API quite easily as well. Say you only wanted properly authenticated users to access your API, well,
you could throw some code like this into your process request functionality (borrowed from an existing app of mine, so there¶s some constants and
variables referenced that aren¶t defined in this snippet):

// figure out if we need to challenge the user

if(empty($_SERVER['PHP_AUTH_DIGEST']))
{
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Digest realm="' . AUTH_REALM . '",qop="auth",nonce="' . uniqid() . '",opaque="' . md5(AUTH_REALM) . '"');
// show the error if they hit cancel
die(RestControllerLib::error(401, true));
}

// now, analayze the PHP_AUTH_DIGEST var

if(!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) || $auth_username != $data['username'])
{
// show the error due to bad auth
die(RestUtils::sendResponse(401));
}
 // so far, everything's good, let's now check the response a bit more...
$A1 = md5($data['username'] . ':' . AUTH_REALM . ':' . $auth_pass);
$A2 = md5($_SERVER['REQUEST_METHOD'] . ':' . $data['uri']);
$valid_response = md5($A1 . ':' . $data['nonce'] . ':' . $data['nc'] . ':' . $data['cnonce'] . ':' . $data['qop'] . ':' . $A2);

// last check..
if($data['response'] != $valid_response)
{
die(RestUtils::sendResponse(401));
}

Pretty cool stuff, huh? With a little bit of code and some clever logic, you can add a fully functional REST API to your apps very quickly. I¶m not just
saying that to cheerlead the concept either, I implemented this stuff into one of my personal frameworks in about half a day, and then spent another half
day adding all sorts of cool magic to it. If you (the reader) are interested in seeing my final implementation, drop me a note in the comments and I¶d be
happy to share it with you! Also, if you¶ve got any cool ideas you¶d like to share, be sure to drop those in the comments as well« if I like it enough, I¶d
even let you guest author your own article on the subject!

:$ "%

 



How to GET, POST, PUT, & DELETE in PHP

APIs have become a very commonplace part of many popular web sites and services« especially REST APIs. I¶ve already discussed how you can roll
your own REST API for your PHP apps, but I¶ve also received countless requests to go over how to actually make RESTful requests. That¶s exactly what
we¶ll take a look at in this article. Before we dive in, however, I want to make sure you¶ve got a basic understanding of how REST APIs work, so if you¶re
a bit shaky or unfamiliar with the concept, head on over to my previous article on REST and read up (you don¶t need to go over the implementation stuff
if you don¶t want, just read the first part of the article). Seriously, do it« this article is written with the assumption you¶re familiar with the concepts of
REST.

Anyway, without any further delay, let¶s take a look at what we¶re going to cover«


& #%%



Every REST request consists of essentially the same basic parts:

˜ 
 ! ± This is the URL we¶ll be making a request against (often referred to as a resource).
˜ 
'
( ± GET, POST, PUT, or DELETE« there are some others out there, but these are the 4 most common ones.
˜ 

 ) ± The parameters we¶ll be supplying to the API, often referred to as the request body.
˜ c

  ± Username and password« we¶ll cover HTTP Digest auth credentials.

And, of course, we¶ll have a few pieces for our response as well:

˜ 


& ± The actual response body the API gave us.

˜ 


c
± The HTTP status code the API responded with.
˜ 


% ± We¶ll also have some other interesting info in the response.

Nothing really unexpected here, everything¶s probably looking like what you¶d expect: a request and a response.

So, on to the answer to the most important question: ³How the heck do you actually make the request?!?!?´

*

+c 

#


You may have already guessed we¶d be using curl (or suspected it perhaps)« and if you didn¶t, well, that¶s what we¶ll be using Anyway, if you¶ve
ever worked with Curl in PHP, you¶re probably aware that making GET and POST requests are pretty straight-forward, but the PUT and DELETE
requests are a little less obvious. Luckily, they¶re pretty easy once you know how to do them, the problem is that they¶re very poorly documented. We¶ll
go over them soon, but let¶s get started with a little code. We¶re going to be building a class that we can use to make requests and deal with their
responses, so why don¶t we build up a bit of a base class, and then start filling things in:

class RestRequest
{
protected $url;
protected $verb;
protected $requestBody;
protected $requestLength;
protected $username;
 protected $password;
protected $acceptType;
protected $responseBody;
protected $responseInfo;

public function __construct ($url = null, $verb = 'GET', $requestBody = null)

{
$this->url = $url;
$this->verb = $verb;
$this->requestBody = $requestBody;
$this->requestLength = 0;
$this->username = null;
$this->password = null;
$this->acceptType = 'application/json';
$this->responseBody = null;
$this->responseInfo = null;

if ($this->requestBody !== null)

{
$this->buildPostBody();
}
}

public function flush ()

{
$this->requestBody = null;
$this->requestLength = 0;
$this->verb = 'GET';
$this->responseBody = null;
$this->responseInfo = null;
}

public function execute ()

{

public function buildPostBody ($data = null)

{

protected function executeGet ($ch)

{

protected function executePost ($ch)

{

protected function executePut ($ch)

{

protected function executeDelete ($ch)

{

protected function doExecute (&$curlHandle)

{

protected function setCurlOpts (&$curlHandle)

{

protected function setAuth (&$curlHandle)

{

}
}
So, what we¶ve got here is essentially all of the functions we¶ll need to make this whole thing work right. We¶ll cover each of the function individually, but
let¶s take a look at the class members:

˜ â  ± The URL we¶ll be requesting against

˜ â
( ± The type of request we¶ll be making (what verb to use)
˜ â

& ± The request body we¶ll send with PUT and POST requests
˜ â

!
" ± An internally used variable for PUT requests (more on this later)
˜ â
)
± The username to use for this request
˜ â  ± I¶ll let you guess
˜ â##

± What kind of content we¶ll accept as a response (not all APIs use this to determine the response format, but we¶ll be robust)
˜ â

& ± The body of our response
˜ â

% ± All the other goodness from our response (status code, etc.)

Not too rough, right? And if you take a look at the constructor, you¶ll see things are pretty straight-forward as well. We¶ve also got a flush function. This
allows us to use the same object to make multiple requests by only clearing out certain member variables (notice username / password aren¶t touched).
You may have also noticed we¶re missing getters / setters« this is simply to keep the code a little shorter. The final class will have them.

:$ "

+


 $

Let¶s go ahead and fill in some of the functions that do prep work for us, and then we¶ll dig into making the requests. Anyway, let¶s take a look at these
³init´ functions..

( 
&
This function will take an array and prepare it for being posted (or put as well):

public function buildPostBody ($data = null)

{
$data = ($data !== null) ? $data : $this->requestBody;

if (!is_array($data))
{
throw new InvalidArgumentException('Invalid data input for postBody. Array expected');
}

$data = http_build_query($data, '', '&');

$this->requestBody = $data;
}

Notice how we will throw exceptions if we receive anything other than an array? This is important, as we don¶t want our data to be malformed (or an error
to be thrown by http_build_query). Also, you may be thinking that I¶m using an exception type that isn¶t defined anywhere« well, it is (if you¶re using PHP
5). I won¶t go off on a tangent, but check out the PHP SPL for more info. All you need to know is that the InvalidArgumentException is already defined for
you


c 
This function will take care of all the curl options common to all our requests:

protected function setCurlOpts (&$curlHandle)

{
curl_setopt($curlHandle, CURLOPT_TIMEOUT, 10);
curl_setopt($curlHandle, CURLOPT_URL, $this->url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, array ('Accept: ' . $this->acceptType));
}


 
If we¶ve got a username and password set on the class, we¶ll set up the auth options on the curl request with this function:

protected function setAuth (&$curlHandle)

{
if ($this->username !== null && $this->password !== null)
{
curl_setopt($curlHandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
curl_setopt($curlHandle, CURLOPT_USERPWD, $this->username . ':' . $this->password);
}
}
I mentioned earlier that we¶re only going to cover HTTP Digest authentication in this class, but you could adapt this function to suit your needs however
you wanted depending on what the API(s) you¶re consuming require.

:$ "




We¶re about ready to cover how to make the individual verb requests, but we need to do just a little bit more work filling in the common functionality.
We¶ll go ahead and create our doExecute and execute functions now:

public function execute ()

{
$ch = curl_init();
$this->setAuth($ch);

try
{
switch (strtoupper($this->verb))
{
case 'GET':
$this->executeGet($ch);
break;
case 'POST':
$this->executePost($ch);
break;
case 'PUT':
$this->executePut($ch);
break;
case 'DELETE':
$this->executeDelete($ch);
break;
default:
throw new InvalidArgumentException('Current verb (' . $this->verb . ') is an invalid REST verb.');
}
}
catch (InvalidArgumentException $e)
{
curl_close($ch);
throw $e;
}
catch (Exception $e)
{
curl_close($ch);
throw $e;
}

protected function doExecute (&$curlHandle)

{
$this->setCurlOpts($curlHandle);
$this->responseBody = curl_exec($curlHandle);
$this->responseInfo = curl_getinfo($curlHandle);

curl_close($curlHandle);
}

Looks like a lot of code, but it¶s actually pretty simple stuff.

First, looking at execute, you¶ll see that we set up a curl handle variable ($ch), and then run the setAuth function. Since we pass $ch around by
reference, the functions will directly manipulate the variable without any need to return it. Now, I could make the $ch a member variable, but for the sake
of this example, I wanted to show how everything gets passed around a little more explicitly. Anyway, the next thing we do is normalize the verb, and run
through our switch statement to determine what function will get executed. If we don¶t find a matching case, we throw an exception. We also wrap the
whole thing in a try / catch block so we can properly catch exceptions, close our curl handle, then throw the exception again (presumably for some other
error handler or try / catch block elsewhere in the code).

Moving on to the doExecute function, you¶ll see all we really do here is set all the common curl options with setCurlOpts, execute the request, and get
the response body and info. We¶ll take a look at those in a bit, but let¶s get to the individual request functions.

Ë



These requests are about as easy as they get. Since your params will be a part of the URL, there isn¶t much to do outside of actually making the
request. So our code is nice and easy:
 protected function executeGet ($ch)
{
$this->doExecute($ch);
}

µNuff said





These too are pretty easy to accomplish, and POSTing with Curl is well-documented. Nonetheless, here¶s what our function looks like:

protected function executePost ($ch)

{
if (!is_string($this->requestBody))
{
$this->buildPostBody();
}

curl_setopt($ch, CURLOPT_POSTFIELDS, $this->requestBody);

curl_setopt($ch, CURLOPT_POST, 1);

$this->doExecute($ch);
}

All we really do here is make sure the request body is a string, and if it isn¶t that means we need to prepare it« so we do. Then we tell Curl to make a
POST request with the provided POST body. That¶s all there is to it! Moving on«



 



Ah, PUT requests« These are the big mystery. Admittedly, there are a few articles out there covering how to do them, but they¶re not super-easy to
come across. I did, however, manage to find a few and here¶s what I came up with:

protected function executePut ($ch)

{
if (!is_string($this->requestBody))
{
$this->buildPostBody();
}

$this->requestLength = strlen($this->requestBody);

$fh = fopen('php://memory', 'rw');

fwrite($fh, $this->requestBody);
rewind($fh);

curl_setopt($ch, CURLOPT_INFILE, $fh);

curl_setopt($ch, CURLOPT_INFILESIZE, $this->requestLength);
curl_setopt($ch, CURLOPT_PUT, true);

$this->doExecute($ch);

fclose($fh);
}

A little funky, right? Well, this boils down to the way PUT requests are technically supposed to work. RESTful APIs don¶t quite use a PUT the way they
were originally intended, which is for file uploads. As such, we need to stream the data to the web server. So we open an internal php memory resource,
write our request body to it, and then pass the handle for that memory resource to curl. We also calculate the size of it (in bytes), so that our full body will
be received on the API side of things. I suppose that doesn¶t necessarily need to make any sense to you, as long as you trust that it works

h!

 



Deletes, when done as they¶re intended (no post body), are easy. Remember, you¶re not really supposed to send any body for a delete request, as
you¶re merely sending a command to a resource (i.e. /api/user/1). Here¶s the code:

protected function executeDelete ($ch)

{
 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$this->doExecute($ch);
}

Now, if you need to send a body for some reason, you can do it by adding the same stuff you use for a PUT request, but swap out the CURLOPT_PUT
line for the existing CURLOPT_CUSTOMREQUEST line that we¶ve got in this function. I don¶t advocate this, but it works like a champ if you need it.






Now that we¶ve got a fully functioning REST requester, let¶s take a look at a response. So, making a request against an imaginary API looks something
like:

$request = new RestRequest('http://example.com/api/user/1', 'GET');

$request->execute();

echo '<pre>' . print_r($request, true) . '</pre>';

Which gives us output similar to:

RestRequest Object
(
[url:protected] => http://example.com/api/user/1
[verb:protected] => GET
[requestBody:protected] =>
[requestLength:protected] => 0
[username:protected] =>
[password:protected] =>
[acceptType:protected] => application/json
[responseBody:protected] => [RESPONSE BODY HERE]
[responseInfo:protected] => Array
(
[url] => http://example.com/api/user/1
[content_type] => application/json
[http_code] => 200
[header_size] => 232
[request_size] => 192
[filetime] => -1
[ssl_verify_result] => 0
[redirect_count] => 0
[total_time] => 0.015693
[namelookup_time] => 0.0004
[connect_time] => 0.000571
[pretransfer_time] => 0.000619
[size_upload] => 0
[size_download] => 4276
[speed_download] => 272478
[speed_upload] => 0
[download_content_length] => 4276
[upload_content_length] => 0
[starttransfer_time] => 0.015655
[redirect_time] => 0
)
)

Take a look at the responseInfo« we¶ve got our status code, and all sorts of other good stuff. And, believe it or not, we¶re done!

  " 

Of course, as with all my samples, there¶s a lot left for you to do. You¶ll probably want to do some processing of the response body and info (such as
extracting the status code), or make a few things more robust, but this is all you should need to get started. Hopefully, after this article and the previous
one, you¶ve got a good idea of how REST APIs work from the server-side, to the client-side, and you¶re ready to jump on the REST bandwagon. If you¶re
not yet convinced« go play with some SOAP APIs, that ought to change your mind

Finally, you can grab the final copy of the class, complete with getters / setters at the link below: