I’ve brought up some of the REST points in this thread in a past discussion on why the “one op per message” rule would be a good one.
I’d recommend taking a look at the standard HTTP headers to see if you can map to those rather than
params. The points Markus has raised are very valid in my opinion, and if we go down the current route the REST community will not accept XDI as REST.
However I think we can do XDI in the REST architectural style.
A specific format for a response could be handled with content negotiation instead of a parameter.
However $mod is another matter. It is is a shortcut for two operations - no matter how you cut it, I think. Also, we have nothing that requires the $del
portion be related in any way to the $add portion. As a result I think Markus is right, $mod will be hard to map without additional constraints, but…
Why can’t we have additional constraints? I’m ignoring ‘because we’d have to change the implementation’, spec is under development - rewrites happen. We
try to make them less painful, but if the TC sees a path to a better spec we shouldn't not go down it because 'we've always done it this way and that would break existing implementations'. At least until we do the first real release of the specs.
The constraints I propose are:
1)
$mod is associated in some way within the message (mechanism is TBD) with a single address within the graph, called the $base
2)
Upon execution of $mod the following takes place
a.
A $del is executed on everything under that address, but not the address itself
b.
A $add is executed using the replacement statements in the message, with using the $base to
transform any relative XRI into an absolute XRI
This makes $mod much more limited in what it can do, but it also makes $mod more focused, more intuitively understandable, and in my opinion makes the semantics
of $mod more sensible.
Ideally each address in a graph can operate as an endpoint for operations on the graph rooted at that address. If that is the case the above definition of
$mod becomes easier.
If not then we’d either have to specify $base in the message somehow or play a little fast and loose to map it to HTTP.
The fast-and-loose thought is to use (misuse according to some) the Range: header like so:
PUT /@example*alice HTTP/1.1
User-Agent: XDI Agent 1.0
Content-Type: application/json+xdi
Range:
xri=@example*alice+email
I’d prefer it if we require every address to serve as an endpoint for operations at that address.
Then we could use:
PUT /@example*alice+email HTTP/1.1
User-Agent: XDI Agent 1.0
Content-Type: application/json+xdi
There are some sticky points to work out, such as Content-Type and literals, but that’s for another discussion.
I think a $mod operation with the above changes could map to HTTP PUT and keep REST purists (like myself) reasonably happy.
Kind regards,
Bill Barnhill
Booz Allen Hamilton - Belcamp,MD
1-443-924-0824|
barnhill_william@bah.com
From: xdi@lists.oasis-open.org [mailto:xdi@lists.oasis-open.org]
On Behalf Of Markus Sabadello
Sent: Wednesday, May 23, 2012 2:28 AM
To: Yuriy Zabrovarnyy
Cc: Michael Schwartz; OASIS - XDI TC; Cameron Hunt; Drummond Reed; Joseph Boyle
Subject: Re: [xdi] How to send XDI message to server?
Like I said, semantics of POST and PUT don't map directly to semantics of $add and $mod.
Of course we could decide that this doesn't matter and that we just do what works.
What parameters would you propose?
Markus
On Tue, May 22, 2012 at 11:40 PM, Yuriy Zabrovarnyy <yzabrovarniy@gmail.com> wrote:
It's important to keep REST interface obvious for others. Direct request transfer via POST cut down advantage of REST and looks more like direct transfer.
1. It's good approach to reuse existing stuff with REST. Mapping between HTTP methods and XDI operations looks pretty natural. See this link
http://en.wikipedia.org/wiki/Representational_state_transfer#Vocabulary_Re-Use_vs._Its_Arbitrary_Extension:_HTTP_and_SOAP
2. Parameters with REST is widely used, for example see OAuth or OpenID specification. I don't see any reason why do we try to avoid parameters usage.
Regards,
Yuriy Z
On Wed, May 23, 2012 at 12:24 AM, Markus Sabadello <markus.sabadello@xdi.org> wrote:
The GET shortcut is limited and only for the public part of the graph. It could be nice for some situations, but I agree it's not necessary.
Everything can simply be done with POST. Everything needed to execute the message should be in the message, which goes into the HTTP body. HTTP query and fragment should not be used.
Markus
On Tue, May 22, 2012 at 11:18 PM, Michael Schwartz <mike@gluu.org> wrote:
Markus,
And where would you communicated references to link contracts?
Multiple operations in one message?
Where would the sender be specified ?
Prima facie, it seems like your design would only be useful for requests to the $public part of a graph. Perhaps this should be specified as an additional MAY feature a server may implement. But I'd rather see one initial comprehensive solution before we support
a shortcut.
- Mike
On Tue, 22 May 2012, Markus Sabadello wrote:
Okay, here's my proposed design.
* A message is sent via HTTP POST (as the full HTTP body, not
encoded as a parameter)
* As a convenient shortcut, HTTP GET is treated like an XDI $get operation
on a single XDI address passed in the URL, e.g.
GET /=markus+email HTTP 1.1
becomes something like
$$msg!1$do/$get/=markus+email
* HTTP DELETE is not supported
* HTTP PUT is not supported
* No HTTP query string or fragment or form-encoded parameters are used
* An Accept: header can be sent by the client to indicate the desired
response format, e.g. JSON, or list of XDI statements.
* A Content-Type: header is sent by the server to indicate the actual
response format.
Markus
On Tue, May 22, 2012 at 11:03 PM, Michael Schwartz <mike@gluu.org> wrote:
Markus and Joseph,
Propose a design... but obviously, we need to address how all elements of
the XDI message would be communicated, not just the operation.
- Mike
On Tue, 22 May 2012, Markus Sabadello wrote:
Thanks Joseph for re-sending..
For an XDI Developer list, I think Google Groups would be easiest.
Yes we have talked about an HTTP REST binding in the past..
The semantics of GET and $get, as well as those of DELETE and $del seem to
be the same, but mapping $add and $mod to POST and PUT is difficult. We
can
of course do whatever we want, but REST purists won't like it.
I don't think any HTTP query parameters should be used.
Markus
On Tue, May 22, 2012 at 10:39 PM, Joseph Boyle
<planetwork@josephboyle.net>**wrote:
Markus, this is Yuriy and Drummond's replies - forwarding to your gmail
since it sounds like your
xdi.org mail lost them.
On May 13, 2012, at 9:32 PM, Drummond Reed wrote:
Yuriy,
Thanks for sending this. I really wish you could join the TC directly so
you could be part of these discussions - we have talked quite a bit
about a
pure REST binding for XDI, and I think there is agreement on your mapping
of the verbs.
I think we're going to reinstate either the XDI Google Group or start a
new XDI.org mailing list on XDI so we can have discussions with XDI
developers who are not on the TC.
Mike, Markus: it makes sense to me that XDI.org should host the XDI
Developer mailing list. If we are going to redo the website, what are our
options for a new mailing list? Or should we restart the Google Group?
=Drummond
On Sat, May 12, 2012 at 3:35 AM, Yuriy Zabrovarnyy <
yzabrovarniy@gmail.com
wrote:
It's very good idea to standardize REST for XDI Messaging. A few points
from my side:
1. HTTP GET
Please consider following example from
http://wiki.oasis-open.org/**xdi/XdiMessagePatterns<http://wiki.oasis-open.org/xdi/XdiMessagePatterns>
@!9999!8888$msg!1234/$()/(=!**1111!2222)
@!9999!8888$msg!1234/$d!/(**data:,2011-04-10T22:22:22Z)
@!9999!8888$msg!1234/$do/=!**1111!2222!3$do
@!9999!8888$msg!1234$do/$get/=**!1111!2222!3+tel
@!9999!8888$msg!1234$do/$get/=**!1111!2222!3+birthdate
Approach with inlined $get operation can NOT be used because here are 2
$get operations.
E.g. GET /=markus+email HTTP 1.1
As solution parameters can be used to pass $get operation nodes.
2. It's important to specify exact names of parameter as it's made for
OAuth and OpenID standards. Except operations message request also
contains
link contract address, graph id, sender and authentication information
(e.g. token).
3. XDI operations as HTTP methods
According to wiki (
http://en.wikipedia.org/wiki/**Representational_state_**transfer<http://en.wikipedia.org/wiki/Representational_state_transfer>)
these
binding between HTTP methods and XDI operations looks logical to me.
GET - retrieve - $get
PUT - replace - $mod
POST - create - $add
DELETE - delete - $del
To summarize it makes sense to provide sample how exactly XDI Message
Request from oasis wiki can be made via REST web service with exact
parameters.
(I can't send email to oasis mail list, therefore mail is sent only to
people who is in my contact list.)
Regards,
Yuriy Z
On Sat, May 12, 2012 at 12:18 AM, Joseph Boyle <
planetwork@josephboyle.net> wrote:
Yes XDI2's looks like a canonical REST interface. I like it.
Sent from my iPhone
On May 11, 2012, at 1:28 PM, Markus Sabadello <
markus.sabadello@xdi.org>
wrote:
Oops sorry I made one mistake..
* HTTP GET is treated like an XDI $get operation on an XDI address
passed in the URL, e.g.
GET /=markus+email HTTP 1.1
becomes something like
$$msg!1$do/$get/=markus+email
On Fri, May 11, 2012 at 10:26 PM, Markus Sabadello <
markus.sabadello@xdi.org> wrote:
Hi all,
During today's XDI TC call I mentioned XDI Messaging.
The one concrete issue I'd like to figure out is how exactly a message
is sent from an XDI client to an XDI server.
As far as I know, current implementations work like this:
OpenXDI:
-------------
* A message is passed as a "message" parameter, either via HTTP GET or
POST
* No asynchronous XDI messaging supported
XDI2 / Project Danube:
-------------
* A message can be sent via HTTP POST (as the full HTTP body, not
encoded as a parameter)
* HTTP GET is treated like an XDI $get operation on an XDI address
passed in the URL, e.g.
GET /=markus+email HTTP 1.1
becomes something like
$$msg!1$do/$get/=markus
* HTTP DELETE is treated like XDI $del
* HTTP PUT is treated like XDI $add
* An Accept: header can be sent to indicate the desired response
format, e.g. JSON, or list of XDI statements
* No asynchronous XDI messaging supported
I have heard several people say that XDI needs an interface that is
RESTful on the HTTP level.
Please discuss on this thread, then we can create an page on the TC
wiki.
BTW there are lots of pages on the TC wiki that need updating.
Markus
---------------------------------------------------------------------
To unsubscribe, e-mail: xdi-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: xdi-help@lists.oasis-open.org