Re: [sca-bindings] Use cases for HTTP binding

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Eric,

Comments inline.

Eric Johnson <eric@tibco.com> wrote on 25/08/2010
19:27:21:

> From: Eric Johnson <eric@tibco.com>
> To: Simon Holdsworth/UK/IBM@IBMGB
> Cc: OASIS Bindings <sca-bindings@lists.oasis-open.org>
> Date: 25/08/2010 19:27
> Subject: Re: [sca-bindings] Use cases for HTTP
binding
> 
> Hi Simon,
> 
> My general worry is that any reference to REST is just confusing,
> insofar as Fielding's dissertation on the subject casts REST as an
> architectural style.  Thus from a terminology perspective, an
HTTP-
> based application can follow a "RESTful" architecture, but
for 
> example, an individual resource cannot be RESTful in any particular
> sense, since an individual resource doesn't have the application's
> hypertext state.
> 
> To the extend that we talk about use-cases for an HTTP-binding, I
> will find it far less distracting to talk about very specific 
> scenarios/usage, and leave aside any question of relative RESTful-ness.

I agree to some extent, however if we
have a reference with an HTTP binding it would seem fairly pointless to
me if that reference could not somehow be configured to be able to retrieve
a resource from a RESTful application - in which case we do need to consider
how a client application is expected to behave in that scenario and how/whether
that can be modelled via a reference with a binding.http.   We either
need to conclude that it cannot be done to any level of usefulness, it
can be done with some limitations, or it can be fully supported via whatever
binding configuration we devise.

> More comments follow:
> 
>> On 08/19/2010 02:50 AM, Simon Holdsworth wrote: 
>> As far as REST goes my preference would be
that we provide a 
>> general-purpose HTTP binding which is flexible enough to be 
>> configured to interact with or provide RESTful services rather
than 
>> standardising a REST-specific binding.  I don't think we
should 
>> position this as a way to implement RESTful resources, rather
as a 
>> way to extend the reach of SCA composites to access RESTful 
>> resources or be accessed from browser widgets. 
> 
> This is a pretty broad notion, though.  How sweeping should it
be?  
> Does the binding indicate which media-types are supported (XHTML,
> HTML, XML, JSON, Atom...), and then provide some sort a transform
> (XSLT, XQuery?) for each possible response?  What if the server
> returns something other than a "200" response?  On
the one side, 
> SOAP has unbounded verbs applied to a single subject (a "service"),
> whereas on the other side an HTTP application (a with a REST-
> architecture) has a fixed set of verbs, but an unbounded set of 
> resources.  I conclude that the mapping between the two approaches
> might be arbitrarily complex.

Not sure if you are talking about a service or reference
here.  A service binding would indicate what media types it accepts
based primarily on the wireFormat configured on the binding.  The
wireFormat would be responsible for returning a response in the right format
based on the client's request.  A reference binding would similarly
derive the content type it requires from the wireFormat.  We would
need to define how the binding reacts to different response codes - possibly
via a mapping from response codes to faults in the interface, or via some
other pluggable mechanism similar to the operationSelector.

The mapping between WSDL operations/messages and HTTP
Method/URL/headers may potentially be complex but we can certainly define
fairly simple scheme that would cover most cases - using JAX-RS as an example
of such a mapping if not directly exploiting it.
 
>> I agree with Bryan's comments regarding allowing more flexibility.
 
>> I would be wary of providing a binding which imposes a specific
>> interface design approach though.   My expectation would
be that 
>> exposing services from an SCA composite to be accessed via HTTP
>> would generally use a specifically designed interface; accessing
>> services via HTTP from an SCA composite may well need to be based
on
>> an existing interface not directly related to the HTTP resource.
 If
>> the resource dictated the interface it would become common for
SCA 
>> composites to have to have a mapping component which translates
>> between the established interface and the one that was created
to 
>> fit in with the HTTP binding. 
>> 
>> As far as JAX-RS goes, I think it would be useful to provide a
>> consistent level of capability, but I don't see it as necessary
to 
>> explicitly support JAX-RS. 
> 
>> Here are a few specific use cases which would motivate flexibility
>> required to support REST: 
> 
>> Access to RESTful resource:  I want to be able to retrieve
some 
>> information about the current state of my business provided as
an 
>> external RESTful resource to influence the behaviour of my 
>> composite.  The resource expects parameters supplied in the
URL 
>> path, optional parameters in the query string, and returns an
XML 
>> document.  I want to make the retrieval based on information
I have 
>> within a complex data structure and set a particular element with
>> the resulting value. 
> 
> Aside from the terminology point which I mentioned above, this begs
> for more detail.  Specifically, are we assuming that we can specify
> a particular media-type, such as an XML form?  Are you then 
> expecting that the binding would transform the result to extract 
> only the data that I expect in my "interface"?  What
sort of media 
> types and data extraction do we need to worry about:
> Subsets of XML
> Subsets of JSON
> (X)HTML (a.k.a. "screen scraping")
> (X)HTML with RDFa

Most likely any of the above.  I would expect
that the wireFormat defined on the HTTP binding for handling response messages
to define the requested media type, and that that wireFormat would be responsible
for mapping the response body into some runtime representation that matches
the schema of the element to which the response is mapped.  I am not
envisaging some complex transformation of that data, or extraction of multiple
elements from that.

>> Also, I (we?) sometimes forget that web pages
these days are 
>> conglomerations of HTTP GET requests - images, CSS, Javascript,
>> frames & iframes, because I tend to perceive it as a single
"page", 
>> when it is anything but.  Retrieving data from these otherwise
>> unmodified web pages could actually require following multiple
links
>> to get to the data that the service actually needs.  Is this
>> encapsulated in the binding, or if not, then where?

This concern I share, as per my comments later in
my note.  The main thing that breaks the model of having the binding
apply to any component type is the leaking of HTTP-ness of the references
to other objects.

> I think I'd much prefer it if we took the approach of identifying
> specific HTTP-application implementation technologies, like Ruby-On-
> Rails or JAX-RS, and talked about how to extract data from 
> applications implemented using those frameworks.  Why?  Those
> frameworks define patterns that we can follow and exploit, whereas
a
> generic JSP-based application doesn't necessarily follow any patterns.

I agree with this.  I would be happy to initially
focus on applications implemented using JAX-RS.  Where possible we
should generalise the support we provide to embrace a wider set of patterns,
but it would at least provide bounds on the initial problem.

> HTTP has a set of headers for indicating how a client expects to 
> receive information.  The client can make media type selection,
> language selection, and timezone selection, in addition to providing
> cookies, authentication details, and caching configuration (If-
> Modified-Since).  Do we expect it to be useful for the client
to 
> cache responses, or not?  Do we expect the data to be sensitive
to 
> any of these other details?
> 
> Does the target server sometimes post "temporary redirects"
for 
> server downtime?  Do we expect the binding to handle those, or
are 
> they treated as "errors" in the SOAP sense?

I would hope that redirects would be handled by the
binding; other functions you describe in terms of content selection would
be derived from binding configuration and wireFormat selection.  
Cookies and caching are something I've not really considered.
 
>> Provision of RESTful resource:  I want to be able to allow
browser 
>> widgets access to a service that I provide from my composite that
>> allows query/update of some aspect of the current state of my
>> business process.  The browser widget supplies parameters
in the URL
>> path and may include a JSON document for update operations.  I
want 
>> to design the interface for the service that I provide based on
the 
>> set of operations I want to make available. 
> 
> Again, I'd love more details.  Thinking about a use-case like
> "updating my preferences" in a standard HTTP-based application,
I 
> get a single form submission to update a set of data.  Whereas,
in 
> an SOAP application, I might wish I had operations for 
> "setEmailDeliveryPreference", "setHomePageDisplayPreference".
 
> Obviously, I could provide a single operation that takes a single
> set of data, as in "updateProfilePreferences", and map that
onto the
> existing HTTP-POST request.  My concern from what you said, "the
set
> of operations I want to make available", I'm not sure whether
you're
> suggesting both possibilities, or really just wrappers around 
> already defined URLs to do a "POST", that is, do you conceive
of the
> HTTP binding as mapping N operations onto one or more HTTP verbs to
> M resources, or is it simply a wrapper around a single HTTP resource
> with a single verb?

In general we could provide the flexibility for any
of the above I think, however I agree I should make my use case more specific

> Expose a Java component which has JAX-RS annotations as an SCA java
> component with an HTTP service binding:  Not so sure about this
one,
> but we might want to consider somehow automatically deriving the 
> configuration for the SCA service binding.http from the JAX-RS 
> annotations.   Note that we don't (to my knowledge) currently
allow 
> a JAX-WS annotated Java component to drive the configuration of a
> binding.ws on an SCA service. 
> 
> In order to support an arbitrary mapping from interface to HTTP 
> message I believe the following would be required at a minimum in
> terms of the binding configuration: 
> 
> For the binding: a base URL, a default wireFormat and operationSelector.
> For each operation in the interface: 
> a URL template which may be absolute or relative
to the base URL.  
> The URL template may include replaceable parameters in the path or
> query string.  The syntax defined for JAX-RS seems as good as
any to
> define the URL template. 
> a mapping from the replaceable parameters to
elements in the input 
> message.  This could be a direct mapping to top-level message
parts,
> or a deeper mapping using XPath for instance. 
> an optional mapping from the HTTP body to an
element in the input 
> message for create/update operations, as above. 
> an optional mapping from the HTTP body to an
element in the output 
> message for retrieve operations, as above. 
> an optional specific wireFormat
> 
> Here I'm limiting the parameter mapping to path and query string.
 I
> know JAX-RS allows other mappings including HTTP headers but I'm not
> sure those are recommended REST practice - the URL path should 
> always identify the resource in the absence of other information.
> 
> One aspect of supporting REST in SCA that does cause concern for me
> is how we would support referenced resources.  Within the body
of 
> the XML or JSON document I just retrieved via my nice impl/protocol
> neutral interface, there may be additional URLs that point to 
> referenced resources (the book's publisher, the queue's queue 
> manager, the list of referenced documents, etc...).  How do I
model 
> those in my interface?  Should the binding automatically go get
them
> too so that I can represent them as complex objects - in which case
> we have to worry about arbitrary linking and cycles?  Or do I
need 
> to have some endpoint reference or other veneer over them to avoid
> exposing the fact that I got this information via use of 
> binding.http rather than some other binding?  Or just bite the
> bullet and have URLs in my interface - in which case how does my 
> component then use that URL to go get that resource?   And when
I 
> return a document from a service which includes referenced 
> resources, how do I construct the URLs for those resources so that
> they point to the correct SCA service binding (or other location)?

> 
> That, it seems, is a critical question.
> 
> -Eric.

> 
> Regards, Simon 
> 
> Bryan Aupperle <aupperle@us.ibm.com> wrote on 13/08/2010 15:25:57:
> 
> > From: Bryan Aupperle <aupperle@us.ibm.com> 
> > To: OASIS Bindings <sca-bindings@lists.oasis-open.org>
> > Date: 13/08/2010 15:34 
> > Subject: Re: [sca-bindings] Use cases for HTTP binding 
> > 
> > This is a good start to the discussion.  Some additional
thoughts/
> > things to consider... 
> > 
> > For accessing an HTTP-based service: 
> > - This does not need not be limited to XML-based results.  The
> > result could be JSON or similar (can be described with XSD+DFDL)
> > - Many services are going to be able to return results in multiple
> > formats.  The binding will need to indicate one. 
> > - There are several ways that request parameters are transmitted,
> > part of the URL, query parameters, in the body of the request,
etc. 
> > we will need to either limit or allow for the common patterns
> > - What is the "scope" of a service (i.e. limit to just
one shape of 
> > data or a set of related shapes)  This may impact the nature
of the 
> > URL specified in the binding as well as the service interface
> > 
> > For providing an HTTP-based service: 
> > - This should also include feeds and modifiable data (e.g. a
PUT 
> > adds or modifies/replaces the input object) 
> > - Do we want to constrain the way request parameters are transmitted?
> > - Same sort of "scope" questions as for accessing an
HTTP-based service 
> > 
> > Overall question (not really related to the binding but more
so to 
> > HTTP-based services): Can we define one or a small set of “generic
> > interfaces” for basic HTTP-based service patterns? 
> > 
> > As Anish pointed out, on a recent call we need to be careful
about 
> > labeling anything REST. 
> > 
> > Bryan Aupperle, Ph.D.
> > STSM, WebSphere Enterprise Platform Software Solution Architect
> > WW Center of Excellence for Enterprise Systems & Banking
Center of 
> > Excellence Application Integration Architect
> > 
> > Research Triangle Park,  NC 
> > +1 919-254-7508 (T/L 444-7508)
> > Internet Address: aupperle@us.ibm.com 
> > 
> 
> > 
> > From: 
> > 
> > Jim Marino <jim.marino@gmail.com> 
> > 
> > To: 
> > 
> > OASIS Bindings <sca-bindings@lists.oasis-open.org> 
> > 
> > Date: 
> > 
> > 08/09/2010 04:04 PM 
> > 
> > Subject: 
> > 
> > Re: [sca-bindings] Use cases for HTTP binding 
> > 
> > 
> > 
> > 
> > 
> > 
> > On Aug 4, 2010, at 2:06 AM, Eric Johnson wrote: 
> > 
> > I agreed to an action item to write up, with respect to the 
> > potential HTTP binding, the two use-cases I discussed in the
> > conference call.  So here goes. 
> > 
> > Description 
> > 
> > Exploit an existing HTTP-based service that has XML-based result.
 
> > More specifically, a JAX-WS or Ruby-On-Rails service, wherein
the 
> > URLs for the service are reasonably predictable.  Map that
to a set 
> > of operations mapped to messages being exchanged 
> > 
> > Preconditions 
> > 
> > "Parameters" to request data are simple strings 
> > Every "read" request needed can be mapped to an HTTP
GET 
> > WSDL portType is described with a small flat set of parameters
on 
> > input and a single XML element upon return 
> > Certain HTTP status codes can be mapped to application level
faults 
> > Authentication/authorization credentials are supplied at deployment,
> > and/or TLS with bi-directional certification validation might
be required. 
> > 
> > What happens: 
> > 
> > In binding the portType to an HTTP GET request, the child elements
> > of the request operation get mapped to parameters on the URL.
 
> > Default mapping is element local name to parameter name.  Binding
> > needs to specify a URL with substitution points.
> > Root element of response document is the response element for
the result.
> > 
> > In case of an HTTP error code, where specified, a fault is mimicked
> > for "replies." 
> > 
> > Post-conditions 
> > 
> > Invocations of the "reference" operation return the
XML results 
> > mapped to the language mapping of said data structure 
> > 
> > 
> 
> > 
> > Description: 
> > 
> > Stateful "monitor" of an service providing 1 or more
atom feeds, 
> > supporting three operations "getNewEntriesForFeedFoo",
> > "getLastNEntriesForFeedFoo", "getContentForFoo"
- per Atom feed. 
> > 
> > Preconditions: 
> > 
> > Service that offers up one or more atom feeds
> > Atom feeds are changing slowly enough that polling for data at
lazy 
> > intervals (1 - 60 minutes) is sufficient
> > Customer has a name for each URL.  Operations in the interface
> > follow a known pattern like getNewEntriesForFeedFoo
> > Customer has particular data that they're interested in from
each 
> > feed, such as author, modification date, ID, other metadata 
> > 
> > What happens 
> > 
> > A service requests an update from a specific specific feed by
> > calling getNewEntriesForFeedFoo (where "Foo" changes
per feed) 
> > 
> > Post-conditions 
> > 
> > Returns a list of new entries, the list of the last N entries
> > requested, or the content for the particular entry. 
> > 
> > 
> > 
> > Note, for this last case, it would be much more natural to define
> > the interface with "interface.atom", wherein the relevant
metadata 
> > would be flagged for each feed, and the content of the root element
> > of a feed entry was established.  This would follow known
mapping 
> > rules to map to a WSDL expression of the same, if that was required.
> > Then again, I filed an issue for letting Assembly allow non-WSDL
> > interface descriptions for a reason....
> > 
> > On the service side, the one use-case I can think of is URL 
> > addressability of read-only service information.  This is
> > essentially the reverse of the first use-case described above,
with 
> > one additional caveat.  It may be desirable to map to multiple
URLs 
> > (.xml, .rdf, .xhtml, .txt), so for the service side of this binding
> > a natural thing, I think would be to specify an XSLT file correlated
> > with a particular MIME type.  In the XML case, that might
be added 
> > as a XSL processing instruction.
> > 
> > None of these use-cases gets at all close to REST, but they seem
> > like the might be useful in the abstract.  I've not got
specific 
> > customer needs that are driving these ideas.
> > 
> > -Eric. 
> > Eric, 
> > 
> > Has it been brought up to do a "REST" binding instead
where 
> > operations are mapped to HTTP verbs and content is mapped to
the 
> > content-type header instead? For Java implementation types, JAX-RS
> > annotations could be used in a way similar to the way JAX-WS
> > annotations are for WS-* protocols. Such an approach may prove
to be
> > more interoperable with other frameworks such as Ruby On Rails
or 
> > .NET (which has something analogous to JAX-RS). I put REST in
quotes
> > since HATEOAS would likely not be accommodated in such a binding.
> > 
> > Jim 
> > 
> > P.S. +1 on allowing non-WSDL interface descriptions.    
> 
> 
> 
> 

> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
> number 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
PO6 3AU 
> 
> 
> 
>

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU