Monday, September 15, 2008

Implementing Rest Service and Client with WSF/PHP

WSO2 WSF/PHP 2.0.0 has support for HTTP verbs GET,POST,DELETE and PUT in its REST support alone with the ability to support custom URL mappings. Lets have a look at the WSF/PHP REST API and how to implement a simple client and service.

Usually, a REST system is build around CRUD ( Create, Read, Update, Delete ) model.

An HTTP POST Request is a creation of a resource. Similarly a GET request is reading, PUT request is updating and DELETE request is deleting.

You can find details of a design of a complex REST system here.

Implementing a PHP Web Service that can expose its operations as REST operations.

For exposing operations as REST operations, WSService constructor provides the option RESTMapping to specify each operation with its corresponding HTTP method and Custom URL that is mapped to the operation.

Lets consider an example.  Consider we have an operations createUserAccount, updateUserAccount, deleteUserAccount, and readUserAccount as the operations of a simple service called ManageUserAccounts.php

Then out operations map would be like

   1: $operations = array("createUserAccount" => "createAccount",

   2:                "updateUserAccount"=>"updateAccount",

   3:                 "deleteUserAccount"=>"deleteAccount",

   4:             "readUserAccount"=>"getAccount");

Here, the actual php functions implementing the business logic are  createAccount, updateAccount, deleteAccount and getAccount.

Now we can map these operations to an HTTP method and a custom URL, so that we can execute these same operations without having to use SOAP. 

   1: $restmap = array ("createUserAccount"=> array("HTTPMethod"=>"POST","RESTLocation"=> "users"),

   2:           "updateUserAccount"=> array("HTTPMethod"=>"PUT","RESTLocation"=> "users"),

   3:           "deleteUserAccount"=> array("HTTPMethod"=>"DELETE","RESTLocation"=> "users"),

   4:           "readUserAccount"=> array("HTTPMethod"=>"GET","RESTLocation"=> "users"));

Note how HTTPMethod is used to specify the HTTP Method that will be used to invoke each operation. For example, we will be using POST method to  invoke "createUserAccount" operation. 

RESTLocation option is used to specify a portion of a URL which will makeup the final URL of the operation. For example, if our service URL  is "http://localhost/samples/ManageUserAcconts.php" then, since we have set "users" as our RESTLocation, the final URL that will make the endpoint would be "http://localhost/samples/ManageUserAcconts.php/users". Note how I have used the same RESTLocation for all four operations. WSF/PHP is able to identify the correct operation using the HTTPMethod when the URL is the same.

Implementing the client

WSClient class which is the Client API in WSF/PHP API enables you to make use of  HTTP verbs POST,GET,DELETE and PUT when making a REST style operation invocation. 

First you need to know the REST endpoint where the resource is located. Consider we are invoking the "readUserAccount'' function defined in above service. Then our endpoint URL is  "http://localhost/samples/ManageUserAcconts.php/users" and HTTPMethod is GET. You can do this request using WSClient as well as using the Web Browser.

   1:     $client = new WSClient( array("to" => "http://localhost/samples/ManageUserAccounts.php/users",

   2:                                   "useSOAP" => FALSE,

   3:                                   "HTTPMethod" => "GET"));


   5:     /** Request Payload String is the XML String send as argument to the operation, 

   6:         In this case, it will be send in query string */


   8:     $responseMessage = $client->request($requestPayloadString);

Similarly you can invoke other operations as well.  I will discuss more details in another blog post.

No comments:

Post a Comment