[CONF] Apache Ode: WSDL 1.1 Extensions for REST (page edited)

Wed, 16 Jul 2008 11:55:35 -0700

Page Edited : ODExSITE : WSDL 1.1 Extensions for REST

WSDL 1.1 Extensions for REST has been edited by Alexis Midon (Jul 16, 2008).

(View changes)

Content:

WSDL 1.1 Extensions for better HTTP/REST description

The Resource-Oriented Architecture defines four concepts:

  1. Resources
  2. Their names (URIs)
  3. Their representations
  4. The link bet ween them

and four properties:

  1. Addressability
  2. Statelesness
  3. Connectedness
  4. A uniform interface

HTTP binding as defined in WSDL 1.1 is not well suitable to implement these concepts and properties, mainly because a port type may access 4 different locations/resources but with only one HTTP method.

To better describe RESTful services, and turn a port type into a "resource type", ODE brings a set of 4 extensions:

  1. one HTTP method per operation (instead of one per binding)
  2. a unique URI Template for all operations
  3. access to HTTP headers
  4. fault support

Further details below.

In this page, we use an imaginary blog service as a use case to illustrate and make things more palpable. We will focus on the resources defined by the following URI template: http://blog.org/post/\{id}
Let's assume that such a resource accept four operations:

  • GET to retrieve a post
  • DELETE to delete it
  • PUT to update the post
  • POST to add a comment to a post

One verb per operation

According to the WSDL 1.1 specification, the verb describing the HTTP method has to be at the binding level. Which implies that the same HTTP method is used by all operations of a given port type. But RESTful services leverage HTTP methods to describe operation on resources. So for instance, if you want to use the following HTTP operations – GET, POST, PUT, DELETE – for a given resource, four different bindings would be required. And consequently four port types and four ports. Quite verbose and unusable, isn't it?

So, this extension is to push down the HTTP verb at the operation level. And if an operation does not have its own verb, then the verb defined at the binding level will be used.
This extension is declared in the namespace: http://www.apache.org/ode/type/extension/http

Please note that ODE supports GET, POST, PUT, DELETE only.

<wsdl:definitions ...
                  xmlns:odex="http://www.apache.org/ode/type/extension/http"/>

    <!-- many wsdl elements are ommited to highlight the interesting part -->

    <wsdl:binding name="binding" type="tns:BlogPortType">
        <wsdl:operation name="GET">
            <odex:binding verb="GET" />
        </wsdl:operation>
        <wsdl:operation name="DELETE">
            <odex:binding verb="DELETE"/>
        </wsdl:operation>
    </wsdl:binding>

URI Template

A RESTful service exposed a set of resources, each of them being accessible through a uniform interface: the HTTP methods. So we need a way to define four operations (at most) for a single resource.

Moreover it's very likely that the resource URI actually describes a set of resources. For instance, the set of posts contained in our imaginary blog: http://blog.org/post/\{post_id}.

HTTP binding offers the http:operation element to set the path of an operation. While the service address is set in the wsdl:port element.
So one could imagine spliting the URL this way: 

<service name="blogService">
        <port name="blogPort" binding="blogPortType">
           <http:address location="http://blog.org"/>
        </port>
  </service>

  <binding name="" type="">
        <http:binding verb=""/>
        <operation name="foo">
           <http:operation location="post/(post_id)"/>
           <input>
               <http:urlReplacement/>
           </input>
           <output/>
        </operation>
  </binding>

However, here 3 issues show up:

  1. the location is not accessible from the End Point Reference. => ODE cannot process it before invoking the external service.
  2. http:urlReplacement is only accepted for GET => what about the uniform interface?!
  3. http:urlReplacement requires all parts of the operation input message to be mentioned in the operation location. Meaning that:
    • => the resource id (in the present example) must be a part of the message.
    • => no parts may be stored in the HTTP body. _this conflicts with a PUT operation for instance. With a PUT you would like to set the id in the url and the resource data in the HTTP request body.

To solve this, ODE allows http:operation elements to be omitted or empty. Then the full resource URI may be set in a single place; the http:address of the wsdl:port element.
Please note that curly brackets '{}' are the argument delimiters in URI templates. So that they could be manipulated with XPath Function

In addition, the http:urlReplacement is relaxed: all parts are not required in the URI template anymore. One part could go into the URI, another into the request body.

<service name="">
        <port name="" binding="">
           <http:address location="http://issues.apache.org/jira/browse/{issue_id}"/>
        </port>
  </service>

  <binding name="" type="">
        <operation name="PUT">
           <!-- location attribute intentionally blank -->
           <http:operation location=""/>
           <odex:binding verb="PUT" xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
           <input>
               <http:urlReplacement/>
               <mime:content type="text/xml" part="issue_content"/>
           </input>
           <output/>
        </operation>
    </binding>

Access to HTTP Headers

Request/Response Headers are

Fault Support

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences

Reply via email to