The OpenSocial REST API is not RESTful

[Dave]

According to the Roy Fielding, the author of the paper that defined REST :
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

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".

- Dave

[John Panzer]

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.

[Dave]

On Mon, Oct 20, 2008 at 5:31 PM, John Panzer <jpa...@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.

- Dave

[John Panzer]

On Mon, Oct 20, 2008 at 2:33 PM, Dave <snoo...@gmail.com> wrote:

On Mon, Oct 20, 2008 at 5:31 PM, John Panzer <jpa...@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).

Beyond that, I don't know.  His comments:

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.

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.

[Subbu Allamaraju]

> 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.

Sincerely,
Subbu
---
http://subbu.org

[Louis Ryan]

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 

[John Panzer]

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). 

[Bill de hÓra]

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.

Bill

[John Panzer]

Not to flog a dead horse, but I did notice one thing in 0.81 which may explain Roy's comment about this being thinly veiled RPC, the "response" root element for the "xml" format:

2.1 Responses

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."

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

[Scott Seely]

John—

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