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.
More comments follow:
On 08/19/2010 02:50 AM, Simon Holdsworth wrote:
OF44E27013.DEE1CDB0-ON80257784.0032CD63-80257784.0035FF1A@uk.ibm.com"
type="cite">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.
OF44E27013.DEE1CDB0-ON80257784.0032CD63-80257784.0035FF1A@uk.ibm.com"
type="cite">
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
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?
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.
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?
OF44E27013.DEE1CDB0-ON80257784.0032CD63-80257784.0035FF1A@uk.ibm.com"
type="cite">
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?
OF44E27013.DEE1CDB0-ON80257784.0032CD63-80257784.0035FF1A@uk.ibm.com"
type="cite">
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.
OF44E27013.DEE1CDB0-ON80257784.0032CD63-80257784.0035FF1A@uk.ibm.com"
type="cite">
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
|