Roy lays out six rules that designers of REST APIs should follow and in the comments (see comment #5) says "The OpenSocial RESTful protocol is not RESTful. It could be made so with some relatively small changes, but right now it is just wrapping RPC results in common Web media types."
I must admit, it is not clear to me how OpenSocial REST API violates the six rules that Roy stated. The API does change any communications protocol, the spec does seem mostly concerned with defining resources, resource names are not dictated and instead discovered via XRDS and there is one bookmarkable entry point (the XRDS file). In my last comment on Roy's blog asked him to spell out those "relatively small changes".
The OpenSocial JSON-RPC API isn't RESTful, but it doesn't claim to be either. Perhaps there is some confusion since originally the OpenSocial Protocol was known as the OpenSocial RESTful Protocol. The JSON-RPC part was added in the spring, and of course doesn't fit under the RESTful umbrella. I suspect that's what he's looking at.
> Roy lays out six rules that designers of REST APIs should follow and > in the comments (see comment #5) says "The OpenSocial RESTful protocol > is not RESTful. It could be made so with some relatively small > changes, but right now it is just wrapping RPC results in common Web > media types."
> I must admit, it is not clear to me how OpenSocial REST API violates > the six rules that Roy stated. The API does change any communications > protocol, the spec does seem mostly concerned with defining resources, > resource names are not dictated and instead discovered via XRDS and > there is one bookmarkable entry point (the XRDS file). In my last > comment on Roy's blog asked him to spell out those "relatively small > changes".
On Mon, Oct 20, 2008 at 5:31 PM, John Panzer <jpan...@google.com> wrote: > The OpenSocial JSON-RPC API isn't RESTful, but it doesn't claim to be > either. Perhaps there is some confusion since originally the OpenSocial > Protocol was known as the OpenSocial RESTful Protocol. The JSON-RPC part > was added in the spring, and of course doesn't fit under the RESTful > umbrella. I suspect that's what he's looking at.
That's what I thought (and hoped) too, but I already pointed out that distinction and as you can see in his comment, he links directly to the RESTful protocol spec.
>> Roy lays out six rules that designers of REST APIs should follow and >> in the comments (see comment #5) says "The OpenSocial RESTful protocol >> is not RESTful. It could be made so with some relatively small >> changes, but right now it is just wrapping RPC results in common Web >> media types."
>> I must admit, it is not clear to me how OpenSocial REST API violates >> the six rules that Roy stated. The API does change any communications >> protocol, the spec does seem mostly concerned with defining resources, >> resource names are not dictated and instead discovered via XRDS and >> there is one bookmarkable entry point (the XRDS file). In my last >> comment on Roy's blog asked him to spell out those "relatively small >> changes".
On Mon, Oct 20, 2008 at 2:33 PM, Dave <snoopd...@gmail.com> wrote:
> On Mon, Oct 20, 2008 at 5:31 PM, John Panzer <jpan...@google.com> wrote: > > The OpenSocial JSON-RPC API isn't RESTful, but it doesn't claim to be > > either. Perhaps there is some confusion since originally the OpenSocial > > Protocol was known as the OpenSocial RESTful Protocol. The JSON-RPC part > > was added in the spring, and of course doesn't fit under the RESTful > > umbrella. I suspect that's what he's looking at.
> That's what I thought (and hoped) too, but I already pointed out that > distinction and as you can see in his comment, he links directly to > the RESTful protocol spec.
Looking at this specific comments, the only thing that the 0.81 spec fails (slightly) is in the media types. It uses application/atom+xml and application/json as the MIME type of the resources used. The application/atom+xml type is I think fine to use because it further qualifies its content with an OpenSocial XML namespace (a URI). The application/json content type is a little more problematic because it's not self descriptive; given such a resource representation, you have to know a priori that it's an OpenSocial resource (and specifically a version 0.81 resource). So if anything fails the test I think that would be it.
Since application/json doesn't define namespaces or other standard ways to further define its type, we could use application/opensocial+json instead (define our own media type and suggest a pattern for others to do the same based on JSON). This would enable those generic tools he talks about to deal with the content by interpreting it properly, regardless of how it found the resource(s).
> right now it is just wrapping RPC results in common Web media types.
> A truly RESTful API looks like hypertext. Every addressable unit of > information carries an address, either explicitly (e.g., link and id > attributes) or implicitly (e.g., derived from the media type definition and > representation structure). Query results are represented by a list of links > with summary information, not by arrays of object representations (query is > not a substitute for identification of resources). Resource representations > are self-descriptive: the client does not need to know if a resource is > OpenSocialist because it is just acting on the representations received.
All of this is true of the OS RESTful API, with the JSON caveat mentioned above.
> Think of it in terms of the Web. How many Web browsers are aware of the > distinction between an online-banking resource and a Wiki resource? None of > them. They don't need to be aware of the resource types. What they need to > be aware of is the potential state transitions — the links and forms — and > what semantics/actions are implied by traversing those links. A browser > represents them as distinct UI controls so that a user can see potential > transitions and anticipate the effect of chosen actions. A spider can follow > them to the extent that the relationships are known to be safe. Typed > relations, specific media types, and action-specific elements provide the > guidance needed for automated agents.
> Looking at this specific comments, the only thing that the 0.81 spec > fails (slightly) is in the media types. It uses application/atom > +xml and application/json as the MIME type of the resources used. > The application/atom+xml type is I think fine to use because it > further qualifies its content with an OpenSocial XML namespace (a > URI). The application/json content type is a little more > problematic because it's not self descriptive; given such a resource > representation, you have to know a priori that it's an OpenSocial > resource (and specifically a version 0.81 resource). So if anything > fails the test I think that would be it.
I have not looked at the latest API that is being developed on this list, but you may still want to consider using a opensocial-specific media type for XML as well. The Atom wrapper does not really compensate for using a generic application/xml media type for atom:content.
> Since application/json doesn't define namespaces or other standard > ways to further define its type, we could use application/opensocial > +json instead (define our own media type and suggest a pattern for > others to do the same based on JSON). This would enable those > generic tools he talks about to deal with the content by > interpreting it properly, regardless of how it found the resource(s).
Even using an "application/opensocial+json" media type across the board is not better than application/json. The key litmus test is to check if a server or a client can guess what is contained in a request or response just by looking at the media type. Different kinds of opensocial resources deserve their own media types.
Am I missing something or does the XRDS binding not already declare all the types appropriately by providing namespaces for them. I did'nt see mentioned in Roy's post that the media item information must be embedded in the response itself and it seems reasonable that it be available canonically via XRDS which I believe he is stating is necessary based on the discoverability requirements outlined in his point #4
On Mon, Oct 20, 2008 at 8:01 PM, Subbu Allamaraju <su...@subbu.org> wrote:
> > Looking at this specific comments, the only thing that the 0.81 spec > > fails (slightly) is in the media types. It uses application/atom > > +xml and application/json as the MIME type of the resources used. > > The application/atom+xml type is I think fine to use because it > > further qualifies its content with an OpenSocial XML namespace (a > > URI). The application/json content type is a little more > > problematic because it's not self descriptive; given such a resource > > representation, you have to know a priori that it's an OpenSocial > > resource (and specifically a version 0.81 resource). So if anything > > fails the test I think that would be it.
> I have not looked at the latest API that is being developed on this > list, but you may still want to consider using a opensocial-specific > media type for XML as well. The Atom wrapper does not really > compensate for using a generic application/xml media type for > atom:content.
> > Since application/json doesn't define namespaces or other standard > > ways to further define its type, we could use application/opensocial > > +json instead (define our own media type and suggest a pattern for > > others to do the same based on JSON). This would enable those > > generic tools he talks about to deal with the content by > > interpreting it properly, regardless of how it found the resource(s).
> Even using an "application/opensocial+json" media type across the > board is not better than application/json. The key litmus test is to > check if a server or a client can guess what is contained in a request > or response just by looking at the media type. Different kinds of > opensocial resources deserve their own media types.
Subbu: Yes, it'd be better to have one MIME type per data type, but I think that having a MIME type that further specifies the data variants is a minimal bar for RESTfulness (there's judgement call here -- we probably wouldn't create a different MIME type for an organization contact vs. a person, though technically it would provide an even better specified data type). I could see us wanting to create opensocial-person, opensocial-activity, opensocial-appdata if it's helpful.
Louis: Yes, the issue is linkability -- in a RESTful design, you do not assume that the only entry points are via the XRDS file. You may get entry points via links from other resources and need to be able to auto-discover what type of data you're dealing with.
So I think that the lack of specificity in the MIME types is a fair critique, but I also think it's a trivial change to fix it (I don't think current clients rely on the types).
On Tue, Oct 21, 2008 at 10:16 AM, Louis Ryan <lr...@google.com> wrote: > Am I missing something or does the XRDS binding not already declare all the > types appropriately by providing namespaces for them. I did'nt see mentioned > in Roy's post that the media item information must be embedded in the > response itself and it seems reasonable that it be available canonically via > XRDS which I believe he is stating is necessary based on the discoverability > requirements outlined in his point #4
> On Mon, Oct 20, 2008 at 8:01 PM, Subbu Allamaraju <su...@subbu.org> wrote:
>> > Looking at this specific comments, the only thing that the 0.81 spec >> > fails (slightly) is in the media types. It uses application/atom >> > +xml and application/json as the MIME type of the resources used. >> > The application/atom+xml type is I think fine to use because it >> > further qualifies its content with an OpenSocial XML namespace (a >> > URI). The application/json content type is a little more >> > problematic because it's not self descriptive; given such a resource >> > representation, you have to know a priori that it's an OpenSocial >> > resource (and specifically a version 0.81 resource). So if anything >> > fails the test I think that would be it.
>> I have not looked at the latest API that is being developed on this >> list, but you may still want to consider using a opensocial-specific >> media type for XML as well. The Atom wrapper does not really >> compensate for using a generic application/xml media type for >> atom:content.
>> > Since application/json doesn't define namespaces or other standard >> > ways to further define its type, we could use application/opensocial >> > +json instead (define our own media type and suggest a pattern for >> > others to do the same based on JSON). This would enable those >> > generic tools he talks about to deal with the content by >> > interpreting it properly, regardless of how it found the resource(s).
>> Even using an "application/opensocial+json" media type across the >> board is not better than application/json. The key litmus test is to >> check if a server or a client can guess what is contained in a request >> or response just by looking at the media type. Different kinds of >> opensocial resources deserve their own media types.
> Subbu: Yes, it'd be better to have one MIME type per data type, but I think
> that having a MIME type that further specifies the data variants is a
> minimal bar for RESTfulness (there's judgement call here -- we probably
> wouldn't create a different MIME type for an organization contact vs. a
> person, though technically it would provide an even better specified data
> type). I could see us wanting to create opensocial-person,
> opensocial-activity, opensocial-appdata if it's helpful.
> Louis: Yes, the issue is linkability -- in a RESTful design, you do not
> assume that the only entry points are via the XRDS file. You may get entry
> points via links from other resources and need to be able to auto-discover
> what type of data you're dealing with.
> So I think that the lack of specificity in the MIME types is a fair
> critique, but I also think it's a trivial change to fix it (I don't think
> current clients rely on the types).
I think the criticism levelled at the spec is overblown; if REST hype
is the problem there are much other APIs more suitable to taking
potshots at. I'm reluctant to confuse the approach taken to the
documentation, which is developer optimized, with the spec itself.
Pragmatically, speaking, people hitting OpenSocial containers will
want limited options to program against and the main job should be to
ensure that the JavaScript API assumptions (an *actual* API) don't
hamper the approach taken by REST oriented clients (eg not having to
version due to content types and being careful around things like
partial updates). I don't see any problem with link following in the
spec except a lack of examples.
My main criticism of baking in XRDS at the front door is that XRDS is
seriously complicated. Sorry to slur, but it has a UDDI/WSDL feel to
it. An AtomPub service document with rel typed links, or HTML META
will do just as well. In any case the easiest way to avoid auto-
discovery failure is to specify a few different entry options - the
problem then will be which should I implement, which is the exactly
the kind of consideration that tends to get lost in web architecture
astronautics.
The structure of the response object returned from a successful request for
the JSON or XML formats is as follows. The root element isresponse, which is
shown explicitly as the root element in XML format, and is the anonymous
root object returned when the format is json (i.e. in JSON, the response
returned is the object value of the response node). The response node MUST
contain the following child nodes, and MAY contain additional nodes that the
Service Provider wishes to add to expose additional data. Note that
startIndex, itemsPerPage, and totalResults are based on
OpenSearch<http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3>
."
Unfortunately this means that input (e.g., new data being POSTed) no loner
has the same data representation between input and output, which is fairly
central to REST-over-HTTP. The fact that the Atom format is still RESTful
is fairly well buried in the specification.
This could be fixed trivially I think, assuming that <response> is really
just a synonym for <collection>. One reason why <response> was proposed a
while ago was to make it clear that request/response related metadata, such
as the HTTP error code and error string, could be embedded therein; I don't
see that in 0.81 though. (It is better to leave this in the HTTP headers
where they have to be anyway.) This assumes that you could define the data
outside the context of a given request -- e.g., a collection of Person
records. Then you document the data format outside the context of any
specific request, give it a unique MIME type, and you're done.
(It's not a bad idea to define the data format in a transport-neutral way
anyway, regardless of REST specifically -- consider archiving, transport
over XMPP, etc.)
-John
On Wed, Oct 22, 2008 at 3:00 PM, Bill de hÓra <b...@dehora.net> wrote:
> On Oct 21, 11:07 pm, "John Panzer" <jpan...@google.com> wrote:
> > Subbu: Yes, it'd be better to have one MIME type per data type, but I
> think
> > that having a MIME type that further specifies the data variants is a
> > minimal bar for RESTfulness (there's judgement call here -- we probably
> > wouldn't create a different MIME type for an organization contact vs. a
> > person, though technically it would provide an even better specified data
> > type). I could see us wanting to create opensocial-person,
> > opensocial-activity, opensocial-appdata if it's helpful.
> > Louis: Yes, the issue is linkability -- in a RESTful design, you do not
> > assume that the only entry points are via the XRDS file. You may get
> entry
> > points via links from other resources and need to be able to
> auto-discover
> > what type of data you're dealing with.
> > So I think that the lack of specificity in the MIME types is a fair
> > critique, but I also think it's a trivial change to fix it (I don't think
> > current clients rely on the types).
> I think the criticism levelled at the spec is overblown; if REST hype
> is the problem there are much other APIs more suitable to taking
> potshots at. I'm reluctant to confuse the approach taken to the
> documentation, which is developer optimized, with the spec itself.
> Pragmatically, speaking, people hitting OpenSocial containers will
> want limited options to program against and the main job should be to
> ensure that the JavaScript API assumptions (an *actual* API) don't
> hamper the approach taken by REST oriented clients (eg not having to
> version due to content types and being careful around things like
> partial updates). I don't see any problem with link following in the
> spec except a lack of examples.
> My main criticism of baking in XRDS at the front door is that XRDS is
> seriously complicated. Sorry to slur, but it has a UDDI/WSDL feel to
> it. An AtomPub service document with rel typed links, or HTML META
> will do just as well. In any case the easiest way to avoid auto-
> discovery failure is to specify a few different entry options - the
> problem then will be which should I implement, which is the exactly
> the kind of consideration that tends to get lost in web architecture
> astronautics.
Do you have a suggested patch to the spec? We might not be able to get this into 0.9, but getting it in within the next couple iterations would be great.
-Scott
From: opensocial-and-gadgets-spec@googlegroups.com [mailto:opensocial-and-gadgets-spec@googlegroups.com] On Behalf Of John Panzer
Sent: Monday, November 10, 2008 5:06 PM
To: opensocial-and-gadgets-spec@googlegroups.com
Subject: [opensocial-and-gadgets-spec] Re: The OpenSocial REST API is not RESTful
The structure of the response object returned from a successful request for the JSON or XML formats is as follows. The root element isresponse, which is shown explicitly as the root element in XML format, and is the anonymous root object returned when the format is json (i.e. in JSON, the response returned is the object value of the response node). The response node MUST contain the following child nodes, and MAY contain additional nodes that the Service Provider wishes to add to expose additional data. Note thatstartIndex, itemsPerPage, and totalResults are based on OpenSearch <http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3> ."
Unfortunately this means that input (e.g., new data being POSTed) no loner has the same data representation between input and output, which is fairly central to REST-over-HTTP. The fact that the Atom format is still RESTful is fairly well buried in the specification.
This could be fixed trivially I think, assuming that <response> is really just a synonym for <collection>. One reason why <response> was proposed a while ago was to make it clear that request/response related metadata, such as the HTTP error code and error string, could be embedded therein; I don't see that in 0.81 though. (It is better to leave this in the HTTP headers where they have to be anyway.) This assumes that you could define the data outside the context of a given request -- e.g., a collection of Person records. Then you document the data format outside the context of any specific request, give it a unique MIME type, and you're done.
(It's not a bad idea to define the data format in a transport-neutral way anyway, regardless of REST specifically -- consider archiving, transport over XMPP, etc.)
-John
On Wed, Oct 22, 2008 at 3:00 PM, Bill de hÓra <b...@dehora.net> wrote:
On Oct 21, 11:07 pm, "John Panzer" <jpan...@google.com> wrote:
> Subbu: Yes, it'd be better to have one MIME type per data type, but I think
> that having a MIME type that further specifies the data variants is a
> minimal bar for RESTfulness (there's judgement call here -- we probably
> wouldn't create a different MIME type for an organization contact vs. a
> person, though technically it would provide an even better specified data
> type). I could see us wanting to create opensocial-person,
> opensocial-activity, opensocial-appdata if it's helpful.
> Louis: Yes, the issue is linkability -- in a RESTful design, you do not
> assume that the only entry points are via the XRDS file. You may get entry
> points via links from other resources and need to be able to auto-discover
> what type of data you're dealing with.
> So I think that the lack of specificity in the MIME types is a fair
> critique, but I also think it's a trivial change to fix it (I don't think
> current clients rely on the types).
I think the criticism levelled at the spec is overblown; if REST hype
is the problem there are much other APIs more suitable to taking
potshots at. I'm reluctant to confuse the approach taken to the
documentation, which is developer optimized, with the spec itself.
Pragmatically, speaking, people hitting OpenSocial containers will
want limited options to program against and the main job should be to
ensure that the JavaScript API assumptions (an *actual* API) don't
hamper the approach taken by REST oriented clients (eg not having to
version due to content types and being careful around things like
partial updates). I don't see any problem with link following in the
spec except a lack of examples.
My main criticism of baking in XRDS at the front door is that XRDS is
seriously complicated. Sorry to slur, but it has a UDDI/WSDL feel to
it. An AtomPub service document with rel typed links, or HTML META
will do just as well. In any case the easiest way to avoid auto-
discovery failure is to specify a few different entry options - the
problem then will be which should I implement, which is the exactly
the kind of consideration that tends to get lost in web architecture
astronautics.
|
