The REST-RPC Binding (binding.restrc) Documentation

This binding supports the rather poorly defined mechanism whereby server actions are performed as a result of an HTTP request. The action performed does not necessarily relate to the verbs defined by HTTP and parameters for the action may be passed either in the URL (when GET is used) or in the body (when POST) is used.

In computing, calling remote procedures with parameters has been called a Remote Procedure
Call (hence rpc) and lately this has become a popular approach to implementing services
in the REST oriented world of HTTP (hence rest.rpc).

Many service providers on the internet use this kind of approach as a light weight alternative to SOAP/HTTP style services.

In this binding the convention is that the name of the action to be performed is provided on the URL as path info directly following the name of the target php script. Parameters for the action are provide as required by the verb used, i.e,

GET /phpscripts/HelloWorld.php/someaction?parama=1&paramb=2 HTTP/1.1
Accept: text/xml,application/xml,application/xhtml+xml,text/html etc.

or

POST /phpscripts/HelloWorld.php/someaction HTTP/1.1
Accept: text/xml,application/xml,application/xhtml+xml,text/html etc.
parama=1&paramb=2

A POST request is expected to have a content-type of application/x-www-form-urlencoded or text/xml. The implication of this is that a method in a service is expected to have zero or more simple typed parameters or zero or 1 SDO typed parameter. A GET request only supports simple types parameters.

Here is a service that uses the REST-RPC binding.

/**
 * @service
 * @binding.restrpc
 */
class HelloWorld
{

    /**
     * @reference
     * @binding.restrpc http://localhost/Greeting.php      
     */
    public $greeting_service;
	
    /**
      * @param string $name
      * @return HelloType http://www.example.org/Hello
      */    
    public function hello($name) 
    { 
        $response = SCA::createDataObject('http://www.example.org/Hello', 'HelloType');
        $response->name = $name;

        $greeting          = $this->greeting_service->greet($name);
        $response->greeting = $greeting->greeting;      
        
        return $response;
    }
}
?>

Service Description

This binding doesn't automatically generate a service description. The service description is the service .php file itslef. It is a manual task for the client developer to read the service .php file and creat service calls accordingly.

Exposing Services

An SCA service is easily exposed as a REST-RPCservice simply by adding a binding.restrpc comment to the service doc comment block. From the previous example,

/**
 * @service
 * @binding.restrpc
 */
class HelloWorld
{
   ...
   
    /**
      * @param string $name
      * @return HelloType http://www.example.org/Hello
      */    
    public function hello($name) 
    { 
        ...
    }
}

All public functions defined in an SCA component exposed as an REST-RPC service can be invoked by REST-RPC clients.

Consuming Services From SCA

An SCA component can call REST-RPC services. In our example the $greeting_service instance variable will be initialized with a REST-RPC proxy to the GreetingService service whenever an instance of the HelloWorld service is constructed.

/**
     * @reference
     * @binding.restrpc http://localhost/Greeting.php      
     */
    public $greeting_service;

Notice that the binding.restrpc annotation also includes a URL to the target service. This is how the proxy knows where to send requests.

$greeting_service can be used to make calls to the remote REST-RPC service.

$this->greeting_service->greet("Fred");

Consuming Services From PHP And Browsers

Plain old PHP can make use of the proxies provided by SCA, for example,

$greeting_service = SCA::getService('http://localhost/Greeting.php', 'restrpc');

Methods on services can then be called on the returned proxy, just as they can in a component.

$this->greeting_service->greet("Fred");

An advantage of using the REST-RPC binding is that you can make requests to the service directly from a browser. For example, placing the following URL in a browser will invoke the greeting service.

http://localhost:80/Greeting.php/greet?name=Fred

Where

• Greeting.php - is the php file holding the service
• greet - is the function name to be called
• name=Fred - is the parameter to the gree function

Deployment

The service is deployed by dropping in into the document root (htdocs) of your web server and is then available to http clients that can provide JSON formatted messages.

Pre-Requisities

No extra pre-requisites are required to expose REST-RPC services. To call REST-RPC service the proxy that this binding generated uses the Curl library so Curl support must also be anabled in PHP using --with-curl.

Outstanding Issues

1. The wrapper allows any content to be returned but the proxy is only able to deal with xml on the return