RESTful URL Mapping in WSF/PHP

In a RESTful design, choose of URLs for web resources are really important. This post about RESTful URL Mapping in WSF/PHP, talks about how you can choose URLs for your resources in a RESTFul manner and How it can be implemented in PHP.

RESTful PHP Web Services - Book

My book on RESTful PHP Web Services is now available for download from Packt Publishing.

What you will learn from this book

• Basic concepts of REST architecture
• Consuming public REST-style services from your PHP applications
• Consuming RESTful web services, such as those from leading APIs such as Flickr, and Yahoo Web Search
• Making your own PHP applications accessible to other applications through a RESTful API
• REST support in the popular Zend framework
• Debugging RESTful services and clients
• A case study of designing a RESTful PHP service from the ground up, and designing clients to consume the service

It is also note worthy that there is a dedicated appendix chapter in this book on using WSO2 WSF/PHP.

DEMO on a SOAP and REST Client with PHP

Amazon ECommerce service is available in both SOAP and REST forms. This guide shows you how to consume the service using either form with the help of a demo application.

Writing a Simple REST and SOAP Service With PHP

WSF/PHP enables you to write a web service in a single script and expose it as both SOAP and REST services. Here is a simple HowTo on creating a Web Service which handle both REST and SOAP requests.

REST Framework for PHP

I have been blogging about WSF/PHP 2.0 being a comprehensive REST framework. Now it is available for you to download.

If you want to design services from scratch, WSF/PHP would be a very good choice, because it provides a natural mapping form design to implementation.

Also, given the fact that this is an extension written in C, it would also provide you with better performance, compared to other REST frameworks purely written in PHP.

RESTful CRUD Data Services Demo

Here is a live demo on RESTful Data Services implemented with WSF/PHP. I wrote a blog about this Demo explaining how you give semantic to the Http Verbs to manipulate (Do CRUD operations on) Resources in RESTful way.

Do REST in PHP - PHP RESTful Data Services

Can you do PHP Data Serivces in REST style with WSF/PHP 2.0.0. Yes certainly you can do it.

Check out this demo about 'RESTful School' and see how can map unique urls to each piece of data you have.

Check "Do REST in PHP - PHP RESTful Data Services" for a guideline of the demo.

Only PHP Library for Creating Both SOAP and REST Services

WSO2, the open source SOA company, today announced the availability of the WSO2 Web Services Framework for PHP (WSF/PHP) 2.0. WSF/PHP is the industry's only PHP scripting language library that enables developers to create and consume both SOAP and REST Web services -- with the security and reliability required for an enterprise service-oriented architecture (SOA).

WSF/PHP 2.0 adds significantly expanded REST functionality, new Data Services, greater interoperability, and extended security. With WSF/PHP 2.0, developers now have a comprehensive framework for deploying PHP services that meet the strict enterprise SOA standards implemented by corporations and governments worldwide.

WSF/PHP 2.0 is part of the WSO2 family of Web Services Framework (WSF) products designed to support enterprises' heterogeneous SOAs. Other WSO2 WSF products include WSF/Ruby, WSF/Perl, WSF/Java, WSF/JavaScript, and WSF/Spring. With the WSF family, enterprises' diverse developer communities have the functionality they need to create Web services in their language of choice.

"WSO2 exists to enable heterogeneous SOAs, and WSF/PHP 2.0 is an important part of that mission. Through WSF/PHP 2.0, enterprises can tap an expansive community of PHP developers by giving them the first comprehensive framework for easily creating both SOAP and REST services," said Dr. Sanjiva Weerawarana, CEO of WSO2. "With our new Data Services and expanded interoperability, WSF/PHP 2.0 also provides a critical bridge between tens of thousands of PHP Web applications and the many enterprise data sources, applications and services driving today's enterprises."

WSF/PHP 2.0 Development, Interoperability and Security Enhancements

With full support for REST, SOAP, and WS-* specifications, WSF/PHP lets a single service be exposed both as a SOAP-style and as a REST-style service using a simple PHP-friendly programming model. WSF/PHP 1.0 provided a REST API along with support for SOAP 1.1 and 1.2, WSDL 1.1 and 2.0, and SOAP Message Transmission Optimization Mechanism (MTOM). WSF/PHP 2.0 adds a comprehensive REST framework featuring custom Uniform Resource Identifier (URI) mapping -- making it easy and intuitive to map a REST API into PHP when creating a Web service.

WSF/PHP 2.0 facilitates Web service creation for the large majority of PHP Web applications that rely on databases. The new WSF/PHP Data Services solution lets developers take data in LAMP(1), WAMP(2), and other PHP-based systems and expose it as a Web service with full WS-* support. Key features include a dbs2php converter tool, and support for multiple database engines, nested queries, and WSDL generation.

Extended interoperability in WSF/PHP 2.0 makes it easier for developers to seamlessly integrate PHP applications with those based on other enterprise platforms. WSF/PHP 2.0 offers much stronger support for the latest WS-* standards, as well as increased testing against Microsoft .NET, the WSO2 WSAS, Axis2/Java, and other J2EE implementations.

    WSF/PHP enterprise security and reliability includes the support
for WS-Security, WS-SecurityPolicy, and WS-ReliableMessaging available
with WSF/PHP 1.0. Version 2.0 of WSF/PHP adds capabilities in four
areas.

    --  Replay detection tracks whether a message is fresh or has been
        previously sent, preventing replay attacks that can lead to
        denial of service.

    --  WS-Trust for issuing, renewing, and validating security tokens
        ensures trusted relationships.

    --  WS-SecureConversation support allows a series of messages (a
        conversation) to be protected by a single session key,
        improving efficiency of the operation.

    --  Support for the Public Key Cryptography Standards (PKCS) makes
        it possible for services written in WSF/PHP to handle multiple
        client x509 certificates simultaneously, further improving
        efficiency.

Other development and performance enhancements in WSF/PHP 2.0 include:

    --  Increased WSDL support includes tools, such as wsdl2php for
        contract-first development of services and clients; the
        ability to generate WSDLs for WSF/PHP Web services scripts;
        and proven support for a range of WSDL styles, including
        support for advanced schemas such as extensions and
        restrictions.

    --  Policy-driven design provides users with a maximum level of
        control by allowing developers to configure the behavior of
        services using policies.

    --  Binary data capability gives users a choice between sending
        and receiving binary data as attachments using either MTOM or
        a SOAP message with attachment (SwA). MTOM in version 2.0 has
        been optimized through caching, enhancing performance.

    --  Expanded deployment models for WSF/PHP 2.0 include several
        platforms -- notably Linux, Windows, and Solaris -- as well as
        seamless integration with Apache and Microsoft Internet
        Information Services (IIS) Web servers.

    --  Enhanced stability to ensure high availability and
        reliability.

    Zend Core Support Featured at ZendCon

With version 2.0, WSF/PHP has been tested and proven to run with Zend Core, Zend's tested, certified and supported version of PHP, which has been widely adopted by enterprises for their production PHP environments. WSF/PHP 2.0 is being launched in conjunction with ZendCon 2008; the Zend/PHP conference runs September 15-18, at the Santa Clara Convention Center in Santa Clara, CA. WSO2 will demonstrate WSF/PHP 2.0 at the Microsoft ZendCon booth.

"Zend and WSO2 are mutually dedicated to serving the diverse needs of PHP developers with world-class open-source software for implementing Web services," said Andi Gutmans, CTO and co-founder at Zend Technologies. "By bringing support for both enterprise-oriented WS-* and REST Web services to our managed PHP production environment, WSO2 joins us in empowering the developers supporting more than 20 million PHP websites with unprecedented flexibility for delivering enterprise-class Web services."

WSF/PHP 2.0 Webinar

WSO2 will present a free webinar, "Introducing Enterprise Web Services with WSO2 WSF/PHP 2.0," which will review how to take advantage of the new REST functionality and WSF/PHP Data Services support. The webinar will run from 9:00-10:00 a.m. Pacific on Tuesday, September 23, 2008. Presenting the webinar will be Selvaratnam Uthaiyashankar, a WSO2 software architect and lead developer of the WSO2 Web Services Frameworks. For more information, visit: http://wso2.com/about/news/wsf-php-sep-08-webinar/.

Availability and Support

The WSO2 Web Services Framework for PHP 2.0 is available for download today. As a fully open source solution released under the Apache License 2.0, it does not carry any software licensing or subscription fees. WSO2 offers a range of service and support options for WSF/PHP 2.0. These include support subscriptions, training, consulting, custom development and development support. For information on service and support packages, visit http://wso2.com.

About WSO2

WSO2 is the open source SOA company founded by pioneers in Web services and the Apache Software Foundation Web services community. The company delivers the only tightly integrated, entirely open source middleware stack that is optimized for SOA. The WSO2 products address the core components of SOAs: service creation, connection, composition and governance. The company is backed by Intel Capital and maintains operations in the United States, United Kingdom and Sri Lanka. For more information, visit http://wso2.com.

(1)LAMP: open source Web platform consisting of Linux, Apache, MySQL, and PHP

(2)WAMP: Web server package containing Windows, Apache, MySQL, and PHP

Trademarks and registered trademarks are the properties of their respective owners.

Source: WSO2

REST Frameworks for PHP

Zend Framework has client and server classes for REST. WSO2 WSF/PHP too has comprehensive support for REST, both client and services.

If your requirements are simple and you are just starting to use REST services, Zend Framework would be a good choice to start with. But if you are going form design to implementation and your application is of enterprise grade, then you have to consider WSO2 WSF/PHP. WSF/PHP is designed in such a manner that you can map your resource design, along with HTTP verb mapping and custom URI mapping to business operations with minimal effort.

Zend Framework REST service and client

Zend framework provides both client and service APIs for REST style implementations. One of the concerns that I have with the Zend_Rest_Service class is that, to use it properly with HTTP verbs, you have to use Zend_Controller. In other words, you have to use MVC model to implement a service properly. This is because, methods like isPost() that can be used to get to know the HTTP verb in use, are at controller layer.

Now, if you think of a service, there should not be MVC in there. You just have the service. It is the client that should use the MVC model and in place of using a database for the model, it should use a service. This is where you go form LAMP to LASP, where S stand for services, or SOA for that matter.

WSF/PHP as a REST Framework

The upcoming 2.0 release of WSF/PHP would have comprehensive support for REST.

PUT and DELETE has been added.

Moreover, we also have the custom URI mapping capabilities. The media types are also supported with WSMessage, so that the user has access to those information as well.

Comprehensive PHP REST Support on the way

The next release of WSO2 WSF/PHP would have PUT and DELETE supported, along with GET and POST, and also, the user will have the luxury of configuring the URL mapping for a given operation.

Nandika has already implemented this and is in the svn trunk of WSF/PHP. Hopefully, we will be able to provide a complete sample on how to use the API, before we do release this feature.

Currently, the next release is planned for the end of July.

REST is CRUD

REST is more close to CRUD. In WSF/PHP, we will make it more RESTful by implementing PUT and DELETE HTTP verbs. If you are wondering about the CRUD mapping:

PUT => create

GET => read

POST => update

DELETE => delete

Get Real with REST

WSF/PHP is the only PHP SOAP API out there that enable you to write a single service script and expose that using both as REST and SOAP with a single deployment.

There was this criticism, however, that the level of REST support was not that RESTful. There is good news now. Apache Axis2/C, the heart of WSF/PHP, has improved the REST support to make it more RESTful. WSF/PHP would soon integrate this improved REST features.

The good news is that not only there would be more support for HTTP methods like PUT and DELETE, it would also provide means to map different PHP functions to a custom resource URI. Keep your fingers crossed.

REST with PHP - More Tips

Earlier, I mentioned how CURL API could be used to do REST with PHP. There is a blog entry by Dimuthu on PHP Web services with fopen. This further shows how to use the PHP functions you are already familiar with to consume Web services in REST style.

Dimuthu has also shown how to do SOAP with fopen, however, I believe it is better to use a framework when using SOAP, because more often than not, SOAP is used when QoS is required, and it would be too tedious to coin all SOAP syntax manually with QoS headers in place.

REST with PHP

The simplest form of REST with PHP comes with XML + CURL. PHP can use the features available within the language to send and receive data, preferably in XML format in case of Web services, over HTTP. One of the most popular techniques is to use the CURL API and GET or POST contents to a URL. This naturally maps to the REST principles. This model is for client side, for consuming services.

For server side, going by the REST principles, one could argue, any hosted PHP script could be considered a REST service. Again, for the sake of Web services, to enable machine to machine interactions, rather than machine to human, XML would be the preferred form of input and output in case of a service. Again, nothing fancy is required, other than the current set of PHP API and extensions.

In short, REST with PHP is pretty simple.

The Need for WS-Security

Yesterday, I wrote about the why we should bother about SOA as PHP users. When we talk about enterprise, security comes to center stage. When you use message passing, with SOA setups, the sensitive messages would have to be secured.

With PHP, there is a well known way of securing client to server communication, that is https. So when talking about REST, one may say, we can use https and secure the messages. True, but is that good enough? For some classes of applications, yes it would. However, many enterprise applications may not be satisfied with that level of security. If you have doubts on this, talk to a security experts. Well, I am not one of those security geeks, but I sure have spoken to few. They would say, the "intruder" could be anywhere.

I borrowed the following image form this article on WSE.

 

At the top, it shows how a protocol-level security such as https could secure your application. The moment the message is delivers, the plain message gets exposed. The "intruder" can easily sneak a peek into the message. As I mentioned earlier, this could be acceptable for some applications, but not all.

The ideal security is the level of security shown in the bottom half of the image, where the message itself is secured. May be the message is signed or encrypted, and sometimes both. Now this cannot done only with transport security like https. You have to secure the message itself. WS-Security specification is meant for just this. It defines how to secure the message itself. So if you want this level of security, you need SOAP Web services. And there are applications, specially enterprise applications that need this level of security.

The good news is that, like Java and .NET, PHP too has full implementation of WS-Security powered by Apache Rampart/C. If you want more information, you can read this article on secure web services with PHP.

Now, one would be wondering, do people really use WS-Security in enterprise applications? Yes they do, and I have seen them. I have seen gaming systems, betting systems and government document transfer systems use WS-Security.  And more often than not, these systems are heterogeneous. They had .NET, Java and yes PHP. I am yet to see a PHP Web service that uses WS-Security in practice, but I sure have seen PHP consuming Web services that enforce security policies implemented in .NET or Java in real world.

Why PHP Users should be Serious about SOA?

PHP is a scripting language, as we all know. The initial purpose was to help Web programmers to build the dynamic web pages, to ease the mess of programming for the dynamic content. Then PHP nicely hooked up with Apache Web server and MySQL. With the rise of Linux, came LAMP, tough P may be said to represent Perl, Python as well as Ruby - the new kind on the block (well, actually then it should be called LAMR), for many, the first thing that comes to mind with P in LAMP is PHP. (The same is true for WAMP as well). The lighting of LAMP gave rise to a new era of applications. PHP gradually evolved form the scripting language that used to ease the generation of dynamic Web pages to a programming language that runs enterprise applications.

Gradually, PHP became a main contender in the enterprise space, playing a role side by side with Java and Microsoft .NET technologies. In addition to the open source presence in many fronts, starting form the php.net downloads to packaged solutions like XAMPP and WampServer, companies like Zend offering enterprise grade products and support, has further strengthened the position of PHP in enterprise applications.

If you look at most of the applications few years ago, and even today, there is a database component. Hence the M in LAMP. The interesting question is, would M hold on to its position in LAMP for the long run, or would it have to let S in SOA to come to that place?

SOA has been a buzz word a few years ago, may be two to three years ago. That was the peak of hype on SOA - in my feeling Ruby and to some extent REST is at the top of the hype right now. By now, hype on SOA has dies down. And many software architects would agree that SOA as an architectural style that is here to stay. It is a fact that, because SOA simplifies connecting systems though loose coupling, almost all enterprise applications would have at lease some elements of SOA within them.

SOA, as a principle, has been there for many years. Hence there have been many traditional technologies, as an example some custom messaging systems, that could be used to realize SOA. However, the rise of Web services brought the SOA term into light and injected new life into it. Both SOAP (or WS-* as some call it) as well as REST could be used to realize SOA with relative eaze. I would not jump into that heated argument on SOAP vs. REST here. However, I must mention that neither WS-* nor REST should be completely ignored, when you think about enterprise applications.

PHP users used to be closely working with Databases. However, looking at the trends, it looks like, more often than not, we would have to talk to services rather than to databases in the future applications. SOA is not full fledged in terms of adoption as of yet. But it is happening. Many businesses and many enterprise applications are in the process of laying out the infrastructure for SOA. Hence, PHP being a programming language increasingly used for enterprise applications would have to consume and provide more services more often than it used to.

It used to be LAMP or WAMP; It is only a matter of time before they become LASP or WASP, where S is for Services. Are you ready to change gears?

SOAP Versions with SoapClient and WSClient

With the PHP SOAP extension, you can use an option in the SoapClient constructor and set the SOAP version to be used.

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => http://test-uri/,
'soap_version' => SOAP_1_2));

The above code sets SOAP 1.2 as the SOAP version to be used. The API document does not mention the default version used in case the user does not provide 'soap_version'. If you want SOAP 1.1, then use 'soap_version' => SOAP_1_1

With the PHP Web services framework, like in the case of SoapClient, you can use the WSClient constructor options to set the SOAP version to be used.

$client = new WSClient(array("to" => http://localhost/tutorial/soap/service.php,
                            "useSOAP" => 1.1));

The above code sets SOAP 1.1 as the SOAP version to be used. As the API document mentions, the default SOAP version used is SOAP 1.2, in case the user does not provide useSOAP option.

Interestingly, "useSOAP" => FALSE can be used as well.

$client = new WSClient(array("to" => http://localhost/tutorial/soap/service.php,


"useSOAP" => FALSE));

This means, instead of sending a SOAP message, send the payload given to the client as Plain Old XML. You can consider this to be a form of REST invocation.

Make your PHP Webservice available for both REST and SOAP consumers

You may have noticed many public web services have deployed their services both as REST services and SOAP services, (e.g. Flickr). You may like to have this feature in your services as well. If you are working with WSO2 Web Service Framework for PHP you don't need to worry about this. Because its engine itself take care of publishing your service both in REST and SOAP form.

In fact one of the indirect advantage, I experienced from this feature is, it allows us to test our Webservice logic in much easier path.

For an example think you are a teacher in a high school and you want to publish examination results through a Webservice.

1 <?php
2 /* exam.php: Simple PHP Webservice for publish students marks */
3
4 /* getResults: This is the operation you going to expose as the Webservice operaion */
5 function getResults($message) {
6
7     /* you hard code the results in an array */
8
9     $results_map = array("Hiro" => "A+",
10                "Clair" => "A+",
11                "Peter" => "A+",
12                "Mohinder" => "A+",
13                "Ando" => "A",
14                "Niki" => "B",
15                "Sylar" => "F",
16                /* you are not worrying to put others results, since they all have 'F's */);
17
18     /* extract the firstName using SimpleXML techniques */
19
20     $xml = new SimpleXMLElement($message->str);
21     $firstName = trim($xml->firstName);
22
23
24     /* you look for the result for the firstName */
25     $result = $results_map[firstName];
26     if($result === NULL)
27     {
28         /* sorry I dont have time to give you a good result.. :( */
29         $result = "F";
30     }
31
32     /* build the response xml and return */
33     return "<result>$result</result>";
34
35 }
36
37 /* create a WSService and specify the service operation */
38 $service = new WSService(array("operations" => array("getResults")));
39
40 $service->reply();
41
42 ?>

So you are done writing and deploying the service by copying it to the Apache Root directory. But you may feel little lazy to write a simple client to test this service. Although it is very simple to write a client (either SOAP or REST) with WSF/PHP, much easier way is to simply open a browser and type following text in the address bar.

"http://mysubject.myhighschool.edu/exam.php/getResults?firstName=Hiro (That is add the the "exam.php/getResults?firstName=Hiro" to the URL where you have hosted your service)

If you see something like

<result>A+</result>

you are done. You can continue testing your service by typing several names and observing whether it returns the correct one.

Actually what you have done here is sending a 'REST' request to the service. If this is working fine your logic is correct. And it will work for the 'SOAP' request as well.

So availability of the services both in REST and SOAP form is a cool feature in WSO2 Webservice framework for PHP which is really helpful not only for consumers but also for service developers.