RESTful PHP Web Services

In the last couple of days, I finished reading the book "RESTful PHP Web Services" by Samisa Abeysinghe. It is a book that  focuses on explaining the REST architectural style and its application to PHP. It is written with a very nice flow, starting with the basic principles, and gradually developing samples based on the REST principles and towards the end,explains the construction of a real world REST application. So by reading this book , the reader is able  understand, grasp and go on to build real world distributed REST applications. It requires only the knowledge of PHP language from the reader.

In addition to explaining the  REST architectural style with interesting examples and applications, the book also explores the REST frameworks that are available, which can be used to implement your applications, instead of writing your own code from scratch. There are two whole chapters dedicated to explore the building of REST Client and Services using Zend Framework  and WSO2 WSF-PHP Framework.

Author

Samisa Abeysinghe has been involved in open source for many many years and has been a main contributor to many highly successful Open Source  Web Services middleware projects like AxisC++, Axis2/C at apache software foundation. In addition, he has been  leading the WSO2 Web Services Framework effort with products like WSF/C, WSF/PHP, WSF/Ruby. Having got years of experience in building distributed middleware, he has put his knowledge and know how in to this book in a very elegant way.

Content of the Book

The book chapters are organized in such a way that, a user with some PHP language knowledge can go through the book and get all the knowledge he needs to build quality applications incorporating REST principles. The First chapter introduces the  concepts and the tools used to build REST applications.  After explaining the principles and concepts, it also explores existing real world REST applications, how best is to utilize these services to enhance your existing applications and then goes on building real client and services. One great aspect about this book is that it comes with a very nice set of samples with all necessary parts nicely explained. The book also covers, rarely explained know how on debugging REST applications. Throughout the book , the best practices involved in building applications are also highlighted.

I would highly recommend this book to anyone expecting to master the techniques of building RESTful applications in PHP. Reading the book will enlighten you not only on building RESTful PHP applications, but also in the broad area of building reusable distributed applications.

Merry Christmas and Happy New Year

Wish everybody a merry Christmas and a happy New Year !!!!!

REST Vs SOAP

Both REST ( Representational states transfer) and SOAP is widely adopted techniques for building distributed systems. REST is an architectural style for implementing systems on top of HTTP infrastructure.  A large number of Specifications has been developed on top of SOAP and there are large number of SOAP stacks both open source and proprietary out there implementing large part of this WS* stack.

Both these d techniques have their advantages and drawbacks. Here are few of the advantages and disadvantages of each paradigm.

REST

Advantages

1. Based on few simple principles which are already in wide adoption on the Web itself

2. Can be implemented very quickly.

3. Ideal for providing simple API's to the users. (Eq Whether Services, Flicker, Yahoo REST services )

4. Amount of learning required to get started is minimum in comparison to SOAP

5. Has a very large following amount the scripting community

Disadvantages

1. If the system is a very large one, then designing based on REST could become a very complex task.

2. Implementing Security on a REST system is one major issues. Although HTTPS, and HTTP Authentication can be used,  they only provide transport level security.

SOAP

Advantages

1. Well designed mature technology

2. Has been widely adopted in industry

3. Large number of SOAP stacks available to choose from.

4. Has support for Both Transport level and message level security which is a big advantage over REST.

5. Supports multiple protocol bindings ( Not just HTTP)

6. Ideal for implementing complex enterprise  systems since the SOAP Stacks cater for security, reliability, transactions ect.

Disadvantages

1. Complex in comparison to REST

2. Big learning curve required

3. Difficult to debug a complex system

One great thing about using WSF/PHP is that it can support Both of these techniques simultaneously. However, if you are building a complex system which require  security, I would always recommend the use of SOAP.

WSO2 Carbon Beta Released

WSO2 Carbon is the new Componetized SOA platform from WSO2. Build on OSGi technology, it enables seamless addition of SOA components to an enterprise deployment of SOA infrastructure, as the need arises.

You can checkout the release notes here.

WSAS - http://tinyurl.com/6nmgue
ESB - http://tinyurl.com/6gxuwr
BPS - http://tinyurl.com/6jtjjj
Registry - http://tinyurl.com/5vd6j5

Getting Started With Axis2/Java

Last week, I was involved with some work in Axis2.  I had to set up Axis2. So I decided to write down the steps incase someone who is going to build axis2 from source and setup a development environment to make some modification to axis2.

Step1. Install maven2

You need to  install Apache Maven 2. Axis2 and many other dependent projects of Axis2 uses maven2 as the build system. Download mavan2 from Apache maven  site.

I used the zip archive of maven. Once you have download, just extract the zip archive a preferred location. For example, my maven2 directory is E:\javasoftware\apache-maven-2.0.9.

When extracted, you will find an xml file named settings.xml in the conf directory. You can edit this file and set configurations according to your preferences. One of the important settings in this file is the maven repository location. Maven repository is a directory when, maven downloads and keeps dependency jar files for building a project. Also the mvn install command will copy the built jar file to this repository at the end of a build process as well.  So I configured the repository to location

E:\java\respository.

<localRepository>E:\javasoftware\repository</localRepository>

There are other details like configuring a proxy. You can find a detailed guide here. 

Create an environment variable MAVEN_HOME and set the maven directory as its value.

Now add the bin directory to your PATH environment variable.  You can directly add the maven bin directory to path and it will work without the MAVEN_HOME. However, it is always preferable to use an separate  environment variable for ease in conformability.

 

Now you have configured maven. Open a new command prompt and type mvn -v to verify whether maven is installed properly.Congratulations, you have successfully configured maven on your system.

Step2. Checkout Axis2 and  build using maven2.

You need to have an svn client installed on your machine in order to checkout source code from the svn server. Assuming that you have an svn client.

Checkout Apache Axis2 from https://svn.apache.org/repos/asf/webservices/axis2/trunk/java

It will take a few minutes to complete the checkout since, axis2 has large amount of source files.  Once you have taken the checkout, open a command prompt, go to axis2 checkout directory, and type mvn clean install to build the axis2 snapshot.

It will take some time to download the dependency jars, compile source and run the tests. Since you are building it for the first time, It is better to run the tests as well. In case you want to skip the Unit tests which will consume time, use the option -Dmaven.test.skip

Once the build is completed, the resulting axis2-SNAPSHOT.jar file will be copied to the folder "org\apache\axis2\axis2\SNAPSHOT" within your maven repository.

Use command mvn -e -X install -Dmaven.test.skip=true -Drelease   to build the distribution. This will include

axis2-SNAPSHOT-war.zip
axis2-SNAPSHOT-src.zip
axis2-SNAPSHOT-bin.zip

You can find some useful maven targets for axis2 here.

Step3. Build the project file for IDEA\Eclipse and configure the project

Use the command mvn idea:idea to build the IntelliJ IDEA project file for axis2. Once this command complete's you will find the axis2.jpr project file in the outer most directory.

If you prefer using eclipse editor, use mvn eclipse:eclipse to build the eclipse project files.

Now double click on the axis2.jpr and open axis2 project in idea IDE. I will go through the steps in configuring the project in IDEA and how to debug ect in my next blog post.

Apache OFBiz Development ( A beginner's tutorial)

Apache Open For Business (OFBiz) is an open source enterprise automation software project.By open source enterprise automation it mean ERP, CRM E-Business/E-Commerce , SCM , Open Source MRP and so on.

Apache OFBiz Development ( A beginner's tutorial ) is a book from Packt Publishing . It is written by two experienced java developers Jonathan Wong and Rupert Howell. It explains the OFBiz functionality, covers from installing OFBiz to fixing an issue in the actual code :).

What you will learn this book.

• Learn what OFBiz is, and what it is capable of doing for business.
• Install and configure OFBiz to optimize system performance.
• Develop a bespoke OFBiz component. Enhance and modify existing components.
• Save time by learning how to re-use existing OFBiz code.
• Explore Entities – the basic units of the framework's Model – to simplify database operations and perform complicated queries.
• Define, create, and call Java services in the Service Engine to build synchronous and asynchronous communications.
• Learn syntax and schema for the OFBiz language: MiniLang. Use MiniLang to speed up your OFBiz development.  
• Acquire valuable development and performance tips that will make your custom applications supreme.

If you are into developing or evaluation open source enterprise automation software at apache, this is a must have book.Here is a sample chapter from the book.

Using command line to debug your Web Service

You can actually run your PHP Web Service on the command line. One may wonder what the use of doing that ?

The main use case is that, you can test your service, without having to write a client. It is specially useful, if your are following the code first approach.  You can find the code for actually doing this in one of the WSF/PHP samples. It is in fact the simplest sample of all. The echo_service.php.

Lets have a look at how this becomes possible.

 WSService->reply() function takes an optional string argument . 

1. You can pass the actual XML string expected from the client to the reply function. Then, the service can be executed on the command line to see the actual executed output from an operation.

However, this would work only in cases where you using SOAP Body dispatching or WS-Addressing.

In SOAP Body dispatching case, the XML qualified name of the child element of soap body is used to identify the operation which should be invoked.

In case of WS-Addressing, the addressing action header is used.

2. Lets look at a code sample on implementing this.  This is the echo_service.php sample that comes with WSF/PHP

<?php

$requestPayloadString = <<<XML
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
     <ns1:echoString xmlns:ns1="http://wso2.org/wsfphp/samples">
         <text>Hello World!</text>
     </ns1:echoString>
    </soapenv:Body>
</soapenv:Envelope>
XML;

function echoFunction($inMessage) {

    $outMessage = new WSMessage($inMessage->str);

    return $outMessage;
}

$operations = array("echoString" => "echoFunction");

$service = new WSService(array("operations" => $operations));
$service->reply($requestPayloadString);

?>

I have highlighted the important code segments. Note how the Expected soap envelope string is passed to the reply() function as an argument.

3. Now you can execute this service on the command line and get the result.

php echo_service.php

Now you should see the expected output soap envelope after invoking the echoString operation.

4. You can also generate the WSDL for the service on the command line as well. Simply set the reply function argument string to "wsdl" or "wsdl2".

$service->reply("wsdl");

5. Now you can re execute the service and get the wsdl for the service on the command line.

php echo_service.php

This is a very useful feature for debugging your hand coded services  :).

Resource Oriented Architecture + PHP

SOA (Service Oriented Architecture ) has been a buzz word for quite some time now and there are large number of frameworks and stacks to support implementing SOA with SOAP being the widely adopted protocol for the implementation of SOA. Similarly ROA( Resource Oriented Architecture talks about a set of guidelines of implementation of a REST architecture. REST architectures can be easily implemented in PHP and has wide popularity among the PHP community since it is based on HTTP and its principles. You can get a good idea about the rest principles by reading this article from infoq.

    As you would have found out from the article above,   Just like SOA talks about services, REST talks about resources.  When using resources, it is important to get the right URL design, then map the correct http methods to the resource. In this sample book chapter from Samisa's  "RESTful PHP Web Services" book, the design of a resource oriented system , and how to implement php clients to access such a rest system is thoroughly  explained. And of course , there is a lot of code samples.

If you are building a REST system, this book is a must have book. It gives you large number of examples and explains the theory and best practices for REST systems. You can get this book from packtpub.com.   

Useful links.

1. REST article

2. Sample Book Chapter

3. Restful Web Services book