RESTful PHP Web Services

5 (1 reviews total)
By Samisa Abeysinghe
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies

About this book

Representational State Transfer (REST) is a form of software architecture; systems that follow it are often called RESTful. It is the architectural style that drives the World Wide Web (the motivation for REST was to capture elements that made the Web successful), and RESTful web services use simple protocols already familiar to web developers. RESTful web services are found in lots of places with big name Web APIs such as Flickr, and Yahoo search following a REST-based approach.

With any architectural style or approach, struggling with its basic concepts is just one problem – implementation in your favorite language is another, and that's where this book comes in. If you're a PHP developer, this book will show you how to create and consume RESTful web services in PHP, and make your services work well in the context of the Web.

You will learn about the basic concepts of REST, and then look at PHP tools, libraries and techniques for working with RESTful web services. You will see how to use other RESTful services from your PHP applications, and also how to engineer your PHP applications to make them RESTful.

This book is about implementing RESTful web services in PHP, and so the book is packed with example code and careful explanations.

Publication date:
October 2008


Chapter 1. Introduction to REST

When we look around the Web today, we can see a whole new breed of web applications compared to those available a few years back. It is a whole new Web, and some even call it as Web 2.0. What makes Web 2.0 possible? Web services are one of the key technologies that make the Web as powerful as we can see it is today.

Web services allow heterogeneous systems to communicate with each other using messages. Because the systems could be heterogeneous, the need for interoperability arises. Hence XML is often used to format the messages. Because XML is in text format, almost all systems can understand the messages and work with each other. Messages are used when it comes to communicating between applications that run on different machines. As an example, in a chat application, the text typed in by the users are wrapped in messages, along with the data that would explain where the message should go and how that should be interpreted and passed between the server applications.

There are various technologies that could be used to implement web services. Representational State Transfer or REST has over time become the preferred technology for web services used in web applications. SOAP web services, also known as WS-* Stack, is also a popular alternative. However, there are criticisms against SOAP style services, especially related to the complexity and bulkiness of messages, when it comes to using the services for web applications. Due to the simplicity, ease of use, and the extensive use of web-based technologies such as HTTP that the Web developers are already familiar with, REST has become more popular among web application developers.

This chapter will introduce REST and the concepts related to REST. As a preview, here are the key REST principles to be discussed in this chapter:

  • The concept of resource (for example, a document is a resource)

  • Every resource given a unique ID (for example, document URL)

  • Resources can be related (for example, one document linking to another)

  • Use of a standard (HTTP, HTML, XML)

  • Resources can have multiple forms (for example, status of a document, updated, validated, deleted)

  • Communication in a stateless fashion using HTTP (for example, subsequent requests not related to each other)


Programmable Web

The initial intended use of the Web was to share information among the members of academic research teams. The academicians wanted an easy way to set up and maintain infrastructure to share their findings. They often wanted to link their documents to that of others and previous related work, so they used hyperlinks to site relevant documents.

A useful abstraction of this principle is a document-based hypermedia model that provides content to the users. In the 1990s, Web was used as a platform for distributing information, and it experienced an explosion of users due to the visual appeal of the hypermedia model.

In sync with the ever-increasing number of users, the number of web-based applications too kept up with the pace. With the large number of applications, the volume of data available on the Web has grown tremendously.

With the data available, apart from web applications that could be accessed by users with a web browser, developers built services that could be used by other applications. The programmable Web is the set of enabling technologies that helps developers build services for the Web.

As an example, think of a weather service. More often than not, people who are travelling are interested in weather. So, a travel-related web application could benefit by presenting the users with weather data on the travel website itself. A developer implementing the travel application could consume a weather service to access the weather information and integrate it with the travel application.

RSS (Really Simple Syndication) is a family of Web feed formats used to publish frequently updated contents such as weather information. An RSS document is essentially an XML document. The Yahoo weather service, located at provides you with an RSS feed of weather. The following code shows how you can access this code using a few lines of PHP:

   $url = '';
   $xml = file_get_contents($url);
   echo $xml;

This piece of code would fetch the RSS feed that contains the New York weather information. In the above example, the returned XML is just echoed. With a bit of XML processing, you can extract the weather information from the RSS feed returned.

Following is a sample response returned from the service.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rss version="2.0" xmlns:yweather="" xmlns:geo="">

<title>Yahoo! Weather - New York, NY</title>
<description>Yahoo! Weather for New York, NY</description>
<lastBuildDate>Sat, 16 Aug 2008 8:51 am EDT</lastBuildDate>
<yweather:location city="New York" region="NY"   country="US"/>
<yweather:units temperature="F" distance="mi" pressure="in" speed="mph"/>
<yweather:wind chill="66"   direction="0"   speed="3" />
<yweather:atmosphere humidity="87"  visibility="7"  pressure="30.02"  rising="1" />
<yweather:astronomy sunrise="6:08 am"   sunset="7:52 pm"/>
<title>Yahoo! Weather</title>
<title>Conditions for New York, NY at 8:51 am EDT</title>
<pubDate>Sat, 16 Aug 2008 8:51 am EDT</pubDate>
<yweather:condition  text="Fair"  code="34"  temp="66"  date="Sat, 16 Aug 2008 8:51 am EDT" />
<img src=""/><br />
<b>Current Conditions:</b><br />
Fair, 66 F<BR />
<BR /><b>Forecast:</b><BR />
Sat - Mostly Sunny. High: 82 Low: 64<br />
Sun - Sunny. High: 88 Low: 67<br />
<br />
<a href="*">Full Forecast at Yahoo! Weather</a><BR/>
(provided by The Weather Channel)<br/>
<yweather:forecast day="Sat" date="16 Aug 2008" low="64" high="82" text="Mostly Sunny" code="34" />
<yweather:forecast day="Sun" date="17 Aug 2008" low="67" high="88" text="Sunny" code="32" />
<guid isPermaLink="false">USNY0996_2008_08_16_8_51_EDT</guid>

Here is how you can process the response to print out the temperature:

$xml = simplexml_load_string($xml);
   $node = $xml->channel->item;
   $children = $node->children('');
   $condition = $children->condition;
   $attributes = $condition->attributes();
   echo $attributes['date'] . " temperature " . $attributes['temp']."F";

Technologies such as AJAX (Asynchronous JavaScript and XML) help to use web services effectively in web applications. AJAX makes Web applications to become more interactive, faster, and more user-friendly. Since AJAX runs within the web browser itself, and there is information pulled to the web browser, while the user is looking at the currently available content, it helps to yield better user experience. Before AJAX became popular, web browsing was stateless, meaning that the user would have to wait till the next page is loaded and establish a relationship among the contents between the consecutive pages. But with AJAX, users can have a state-full experience, meaning that the next related content would be pulled down to the web browser asynchronously and the effort required to correlate the related content would be minimal. While the user is viewing a web page, an HTTP request could be sent to a server and data could be retrieved in an XML format and a part of the page is updated. As an example, the weather information could be updated in real time without refreshing the whole page, so the user experience is maximized and the web application becomes more appealing to the users.


HTTP and Web Services

Programmable Web uses HTTP as the transportation medium and, most of the time, XML as the message format. In other words, programmable Web could be considered as XML over HTTP. XML is not the only data format available in the programmable Web today. There are a large number of formats available, including HTML, XML, JSON, RSS, Atom, CSV and many other custom formats. Among Web developers, Plain-Old-XML (POX) and JavaScript Object Notation (JSON) are often popular. Though XML is the most popular message format, JSON also enjoys wide acceptance because it is a lightweight data-interchange format. Human Web is HTML over HTTP and the HTML documents are retrieved from web servers rendered by the web browsers and presented to humans in a visually appealing form. When you browse the Web, you access resources using a URI (Uniform Resource Indicator) typed into the address bar of the web browser. The browser uses HTTP GET request and fetches the resources, and the web server will respond with a message filled with the content of the requested resource. Browsers can access a variety of resources using the URIs that include images, videos, and more. Web browsers also use HTTP POST requests to post data filled in by users using forms into web servers. Web servers would process those data and respond accordingly. The HTTP requests can point to URIs that are capable of mapping the request to XML documents representing some forms of data, and those XML documents are processed and the data is consumed by programs.

HTTP is a transport protocol. The HTTP protocol has provisions to represent success or failure status information as well as how the data would be contained in request and response. HTTP by design is a stateless protocol because each request is executed independently, without any knowledge of the requests that came before it.

XML is the data encoding mechanism used in the messages sent. The application-specific data, or in other words, data that relates to business logic would be contained in the XML message.

Let's have a look at an example. Flickr exposes an Application Programming Interface (API) that can be used to manage photos There is a test echo API. Please note that you need an API key to use this API and the API documentation given in the aforementioned URL contains details on how to get one. Following is the sample PHP code to access the echo method:

   $base_url = '';
   $query_string = '';
   $params = array (
      'method' => 'flickr.test.echo',
      'name' => 'Sami',
      'api_key' => 'YOUR_API_KEY'
   foreach ($params as $key => $value) {
      $query_string .= "$key=" . urlencode($value) . "&";
   $url = $base_url . "?" . $query_string;
   $client = curl_init($url);
   curl_setopt($client, CURLOPT_RETURNTRANSFER, 1);
   $xml = curl_exec($client);
   echo $xml; 


Please remember to replace 'YOUR_API_KEY' with your API key in the above code before you try it.

Let's look at the HTTP request and response exchanged between the server and the client to understand the format of the messages exchanged.


GET /services/rest/?method=flickr.test.echo&name=Sami&api_key=YOUR_API_KEY& HTTP/1.1

The above request is a GET Request. GET command is immediately followed by the resource location. The resource location that we are accessing is /services/rest/. What follows the location are the parameters. We have three parameters encoded in the request. The method, name, and API key ? character indicates the start of parameters, and parameters are separated from each other using the & character. The final element in the first line of the request is the version of the protocol we are using, in this example HTTP 1.1. The next request header is Host. The resource that we mentioned in the first line is residing on the host


HTTP/1.1 200 OK
Date: Mon, 03 Mar 2008 02:44:19 GMT
Set-Cookie: cookie_l10n=en-us%3Bus; expires=Thursday, 03-Mar-11 02:44:19 GMT; path=/;
Set-Cookie: cookie_intl=deleted; expires=Sunday, 04-Mar-07 02:44:18 GMT; path=/;
Content-Length: 167
Cache-Control: private
Vary: Accept-Encoding
Connection: close
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">

The first line of the response mentions the HTTP protocol version in use, followed by the status code, indicating the status of the response. In this example, we got a 200 OK, which means that the request we sent resulted in a successful response. Followed by the first line, we can see several lines containing various HTTP headers. The HTTP headers and the response body are separated by an empty line. As you can see, the response body contains an XML document.

In the above example, we accessed a resource via a URI,, and we got back an XML document in response. We just witnessed a web service over HTTP in action. Accessing resources via URIs is one of the key principles behind the REST web services. In fact, in the above example, we used Flickr's REST API.


What is REST?

REST is a software architecture style that can be followed while designing software systems. REST is an ideal design style to be followed for web services based software applications. The principles related to REST were first described by Roy Fielding in his Ph.D. dissertation. You can find the chapter that describes REST in that dissertation here: Following are the key REST principles in brief:

  • Provide every resource with a unique ID, for example, a URI

  • Link resources with each other, establishing relationships among resources

  • Use standard methods (HTTP, media types, XML)

  • Resources can have multiple representations that reflect different application states

  • The communication should be stateless using the HTTP

Often, REST architectural style is referred to as the architectural style of the Web. Most of today's web applications demonstrate the characteristics of REST architectural style while building services on the Web.

While using REST, a client/server approach is used to separate user interface from data storage. The client/server interaction is stateless and the interactions use a uniform interface.

One of the key elements in the REST architecture is the concept of a resource. Servers host the resources and clients consume those resources. Any information that can be named can be a resource. According to this definition, a document, an image, and today's weather in New York are all examples of resources.

A resource has a resource identifier, a URI, associated with it. In other words, every piece of information has its own URI. This is also a key principle of the Semantic Web, which is an evolving extension of the World Wide Web in which the semantics of information and services on the Web are defined.

A resource can also have an associated representation, a document can be an HTML document, an image can be JPEG binary data and weather data can be represented using an XML document.

A given resource can also have an associated metadata such as media-type and last the modified time. Metadata is useful for consuming a resource. As an example, we can check the last modified time of weather data to see if we have any new updates on weather. We can fetch the resource based on control data that gives an idea on the novelty of the resource. If weather data has not been modified since the last time we fetched it, then there is no point in fetching a new copy of the same old data.


HTTP Methods

Earlier in the section, "HTTP and web services", we discussed the importance of HTTP as a transport protocol for web services. The simplicity and wide adoption in terms of almost all platforms supporting it has made HTTP the superior transportation of the Internet. REST architecture style can benefit from the elements of HTTP by applying REST concepts while implementing applications that run on the Web.

The extensibility and flexibility of the HTTP protocol has contributed a great deal to the success of the Web, and is considered the protocol of the Web today. HTTP protocol can be used to access resources, not only HTML pages, but all types of resources including images, videos, and applications.

When accessing resources with HTTP, a resource identifier is specified along with the action to be performed on that resource. URIs identify the resource. The action to be performed is defined using an HTTP verb. There is a set of HTTP verbs and each verb can have an associated semantics that helps to identify the action to be performed on the resource.

The following table summarizes the HTTP verbs and how they apply while using REST.




Retrieves a resource identified by a URI.


Sends a resource to the server. Updates the resource in the location identified by the URI.


Sends a resource to the server, to be stored in the location identified by the URI.


Deletes a resource identified by a URI.


Retrieves the metadata of a resource identified by the URI.

These HTTP verbs could be viewed in terms of how we can interact with a resource during the life cycle of a resource. PUT creates a resource, and starts the life cycle. GET retrieves the resource and HEAD query for the metadata. POST can be used to update the resource. Even though, in the context of using a web browser, a POST request could have an associated resource returned, in the context of REST, POST should ideally be used for the purpose of updating resources. GET, HEAD and POST can be used to make use of the resource during the lifetime of a resource. DELETE ends the life cycle of a resource. HTTP verbs help to provide a uniform interface for interacting with resources, which is a key principle of REST architectural style.

Let us consider an example. Say, there is a game of football. When a player comes to play, either at the start of the game or as a substitute, we can use PUT verb and create the player resource. This player can have a unique resource identifier, as an example While the player keeps on playing, POST verb could be used to update the goals scored and the fouls committed by the player resource, and those who access the game information can use the GET operation to access the latest score and committed fouls details for that player resource. When the player gets substituted, DELETE operation could be used to end the player resource life cycle and a new player would replace him/her.

On the Web today, developers mostly use GET and POST, and rarely use PUT and DELETE. One of the key reasons for this situation is the restrictions applied by web servers on these methods. In addition, there are web server modules like the DAV module ( that provides an extension to the HTTP/1.1 protocol that allows clients to perform remote web content authoring operations. This means that in real world applications, developers tend to use POST for creation and deletion operations of resources, in addition to modifications. One of the excuses for not using PUT and DELETE is the fact that firewalls tend to block them. However, it would be good practice to use PUT and DELETE whenever possible rather than overloading POST to implement create and delete. By doing so, you can prevent accidental operations such as deletion of a resource while the user really wanted to update a resource with POST. This makes the API less ambiguous as well. documents how to make use of the HTTP PUT method.


The Need for RESTful Web Services

As we discussed earlier in this chapter, the advent of services has revolutionized the way web applications are developed and hence the way we use the Web. Out of the web applications we use today, a great majority of applications are written using PHP. Popular applications such as Flickr (, Wordpress ( and many others are PHP based. According to the TIOBE programming community index [], PHP is the fourth most used programming language and the most used scripting language. Given the wide adoption of PHP and the increasing awareness of REST, it is timely that we look into the ways in which we can do REST with PHP.

By combining the dynamic Web by PHP and mashups by REST and AJAX, we get a new breed of powerful web applications that would drive the future Web to new heights.

Rather than developing all application components in-house, and spending hours on debugging and fixing them, the web services allows us to use proven and tested applications as part of our own application. It is also noteworthy that the volume of data contained within web services and the services available today exposes an enormous volume of data for the taking by the web application developers. If we are building a social networking application and want to add a feature to share photos, we can use the Flickr API and add that functionality rather than writing our own photo sharing application. And the users would be happy because now they can share the photos they have already uploaded, rather than uploading them again, and maintaining the same images at multiple places.

Given the increasing number of services, and the drive towards the REST style architecture for services on the Web, PHP web application developers need to know how to consume REST services, how to build services themselves, and how to design their web applications so that they can reap maximum benefits from REST services for their applications.


REST Tools and Frameworks in PHP

There are many frameworks and tools in PHP that can help users build RESTful applications with ease. To consume services, that is to write clients for existing services, you can start with simple PHP API elements and implement clients. We already saw in some of the samples that were presented earlier in this chapter as to how this can be done.

XML Parsers

Since bulk of the services use XML, XML tools would be handy for both build requests and parse responses on the client side. On server side too, XML tools are required to do the reverse, to parse the request and build the response.

There are many XML APIs available in PHP, from those, the DOM API and the SimpleXML API are the most popular.

The DOM extension ( allows you to operate on XML documents through the DOM API. The API is fully object-oriented, and adheres to the DOM standards, hence most of the classes are equivalent to those concepts found in DOM specification. It helps to have the DOM standard document available while using this API.

The SimpleXML extension ( provides a very simple and easy to use API to work with XML documents in PHP. The PHP object model that could be built out of an XML document using SimpleXML can be processed with normal PHP property selectors and array iterators, making PHP developers' lives much easy when it comes to working with XML constructs using already familiar PHP constructs.

Tools for Accessing Services

For accessing services we need an HTTP client. We can use file_get_contents ( to access not only local files but also those located on remote servers over HTTP. We used this function in the weather sample.

   $url = '';
   $xml = file_get_contents($url);

However, file_get_contents uses GET, you would need considerable extra work to use a different verb like POST. Also, fopen wrappers need to be enabled to let file_get_contents() access remote files. System administrators may disable fopen wrappers due to security concerns.

The solution to the limitations associated with file_get_contents is to use an HTTP client library such as CURL ( CURL PHP API is a wrapper of libcurl (, a library that allows you to communicate using many different types of protocols. It supports HTTP verbs such as POST and PUT in addition to GET.

Following code segment shows how to POST some XML data to a URL.

   $client = curl_init($url);
   curl_setopt($client, CURLOPT_RETURNTRANSFER, 1);
   // POST XML data with our curl call
   curl_setopt($client, CURLOPT_POST, 1);
   curl_setopt($client, CURLOPT_POSTFIELDS, $xml_data);
   $data = curl_exec($client); 

CURL and file_get_contents are the simple PHP API elements that you can use to work with REST style services. CURL is a PHP extension that is required to be loaded in the PHP configuration file php.ini. file_get_contents, which is only available in PHP versions 4.3 and later. Most of the frameworks that we are going to discuss in the following section provide easy to use client APIs to consume services.

Providing Services

While providing services, you can consider any PHP script hosted with a web server, such as Apache httpd, to be a REST style service, because going by the REST principles, the hosted PHP script will have a URI and it will be providing some information to the users who will be accessing it. So it is a resource.

While implementing services that are to be used in the long run and thus maintained, just hosting some PHP scripts and calling them services would not scale. There needs to be some good design principles that we need to adhere to, and we will discuss those later in this book. There are various PHP frameworks that help us build REST style services adhering to good RESTful designing principles. The following section introduces some popular PHP REST frameworks.

PHP REST Frameworks

The following table lists some PHP frameworks that help you build REST style applications.


Tonic is an open-source RESTFul web application development PHP library. It is designed so that the user can build RESTFul applications in the correct way. The concept of resources are given due prominence, and the library gives the developer the liberty to go about designing the application.


Konstrukt is a RESTFul framework of controllers for PHP5. The controllers are resources and the URI-to-controller mapping gives the application a logical structure. The framework exposes the HTTP methods to the developer and enables the developer to customize the application the way he or she wants.

Zend Framework

The Zend Framework provides both client and server APIs to deal with REST services and clients. Zend_Rest_Server is the class that you can use to provide REST style services. Zend_Rest_Client class can be used to consume REST style services. The Server class is capable of exposing functions and classes using a meaningful and simple XML format. When accessing these services using the Client class, it is possible to retrieve the return data from the remote call easily. The Client class can also be used to consume services that do not use Zend_Rest_Server class to implement the services.


WSO2 web services framework for PHP has comprehensive support for REST style services and clients. You can both provide and consume services using REST principles. WSService and WSClient classes can be used on server side and client side respectively. The advantage of this framework is that a given service can be exposed both as a REST service as well as a SOAP service simultaneously.


Madeam is a rapid application development PHP Framework based on MVC (Model-View-Controller) principle. It allows quick prototyping and deployment of web applications and includes support for building REST style applications.


dbscript is a Web development framework. Key features of this framework include RESTful handling of URLs, HTTP style controllers, and support for Atom over HTTP.

What Framework to Use

Given the number of frameworks available, it would be a challenge to make a choice. As always, selecting one from the many alternatives available has to be based on the requirements of the application to be developed.

Tonic helps to adhere to correct REST principles, but may lack maturity as compared to a framework like the Zend Framework. The same applies to Konstrukt.

Zend Framework is a very mature framework and in addition to REST support, it is equipped with a very useful set of PHP library APIs that would come in handy while developing PHP applications.

WSO2 WSF/PHP would be a good choice if there is a need to make use of advanced web services, especially SOAP based web services alongside REST style services. WSO2 WSF/PHP provides an easy mapping from application design to implementation, when it comes to REST style applications.

Madeam would be ideal for applications adhering to a Model-View-Controller (MVC) design principle. However, note that, while developing REST style applications, more than the presentation, that is the View, we are more interested in resource design.

One of the noteworthy attributes of dbscript is its built-in capabilities to handle feed formats such as Atom.

For complete novices, it would be advisable to start with the Zend Framework and then move on to WSO2 WSF/PHP because Zend framework has an easy to use API for simple services and clients and once there is a good understanding on the principles one can move on to the WSO2 WSF/PHP, which has provision for advance use.



This chapter introduced the concepts related to programmable Web, showed how HTTP and web services are related to each other, introduced the principles behind REST, explained how HTTP verbs are used in REST applications, explained the need for RESTFul web services while building PHP web applications, and introduced some frameworks and tools that can be used to work with REST in PHP.

REST is an architectural style with the concept of resource at its heart and with which we can build web services. REST principles can be applied with HTTP to build powerful services for the Web.

In this chapter, we also saw some bits and pieces of PHP code that can be used to access REST services that are publicly available. By now, you should have a general understanding of what REST is all about. In the next chapter, we will look into how PHP can be used to consume public REST style services in a bit more detail.

About the Author

  • Samisa Abeysinghe

    Samisa Abeysinghe is Director, Engineering at WSO2. Samisa pioneered the Apache Axis2/C effort and architected the core of the Apache Axis2/C Web services engine. He continues to be an active contributor in the Apache Axis2/C project. His involvement in open-source projects began in 2004 when he started working with the Apache Axis C/C++ project.

    Prior to his current role, Samisa played the project lead role for the WSO2 Web services Framework for PHP project, which provides comprehensive support for building both SOAP and REST services and clients.

    Browse publications by this author

Latest Reviews

(1 reviews total)
Fast and efficient purchase and delivery
RESTful PHP Web Services
Unlock this book and the full library for FREE
Start free trial