The REST-Resource Binding (binding.restresource) Documentation

This binding deals with resources in the spirit of HTTP. Service developers implement a set up template methods which support a number of operations on a resource, namely;

• create - create a new resource
• retrieve - retrieve and existing resource
• update - update an existing resource
• delete - delete an existing resource
• enumerate - list all existing resources

Here is a service that uses the rest resource binding.

/**
 * @service
 * @binding.restresource
 * @types urn::orderNS Orders.xsd
 */
class Orders implements SCA_Bindings_restresource_ResourceTemplate
{
           
   
   /**
     * Insert $resource into the resource collection
     *
     * @param OrderType $resource urn::orderNS
     * @return string absolute URL to the new resource
     *
     **/
    public function create($resource){
        ...
    }

    /**
     * returns the resource identified by $id
     *
     * @param string $id
     * @return OrderType urn::orderNS    
     *
     **/
    public function retrieve($id){
       ...
    }

    /**
     * $id is a string that identifies a resource, $resource
     * is the new version of the resource for this id
     * returns an sdo
     *
     * @param string $id     
     * @param OrderType $resource urn::orderNS     
     **/
    public function update($id, $resource){
         ...    
    }

    /**
     * Deletes the resource for $id 
     * returns void
     *
     * @param string $id    
     **/        
    public function delete($id){
         ...
    }

    /**
     * Returns all of the resources 
     *
     * @return OrdersType urn::orderNS
     *
     **/ 
    public function enumerate(){
        ...
    }	
}

How the resource are actually managed inside the service is up to the service implementation but the rest resource binding enforces the following rules.

HTTP Operation, URL and Resource Mapping

POST with form content (x-www-form-urlencoded) is not supported.

Service Description

This binding doesn't automatically generate a service description. The service interface is the standard POST, GET, UPDATE, DELETE HTTP verbs.

Exposing Services

An SCA service is easily exposed as a REST-RPCservice simply by adding a binding.restresource comment to the service doc comment block. All of the methods defined in the SCA_Bindings_restresource_ResourceTemplate interface must be implemented but the service class doesn't have to physically implment this interface.

Consuming Services From SCA

An SCA component can call rest resource services. For example,

/**
     * @reference
     * @binding.restresource http://localhost:80/examples/SCA/RestResource/Orders.php
     * @types urn::orderNS Orders.xsd
     */
    public $orders_service;

Pre-Requisities

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

Outstanding Issues

1. If the service class does explicitly implement the ResourceTemplate interface then the statement ( include 'SCA/SCA.php'; ) must come at the bottom of the file as the class_exists function operates differently when your class implements an interface and this effects the behaviour of SCA

1. No queury parameters or user credentials are passed explicitly into the
   service currently although they are available directly from PHP.