DRAFT: Charter for RESTful JSON

[Ernest Prabhakar]

Hi all,

In trying to follow all the various discussions, it seems to me that
we could use a concrete problem statement. I've put together an
initial draft, with links to the relevant resources:

http://microformats.org/wiki/rest/json

Hopefully we can converge on a prioritized list of goals/constraints,
as well as compile all the relevant resources in one place. Feel free
to sign up and edit the wiki, though policy decisions are probably
best discussed here on the list.

-- Ernie P.

The goal of the RESTful JSON project is to develop a series of
conventions for:
• URLs
• HTTP methods
• HTTP headers
• JSON fields
that:
• is maximally compatible with existing (RESTful, generic) clients
• enables partial updates
• allows paging and/or partial returns of large datasets
• standardizes linking to related resources
• use of hypermedia (links + context) to manage application state
• does NOT become a full-fledged RPC solution

[Benoît Fleury]

Hi,

just a few questions/comments regarding this list of requirements.

 * R1: what do you mean by compatible? How to evaluate the compatibility? Do you have example of REST clients?

 * R2: I think a detailed scenario of partial update would help to understand the consequences of this requirement

 * R4+R5: Doesn't the requirement 5 answers to the requirement 4? Use explicit URIs to link resources? Did I misunderstood one of the requirement?

 * R5: too vague for me. It could be a list of "RPC patterns" to avoid.

Benoit

2008/9/2 Ernest Prabhakar <ernest.p...@gmail.com>

[Kris Zyp]

This looks like a good start, the one thing I would feel is important is the
identification of subresources, but that is part of the convention of URLs
(and you included that).
Kris

[Joe Gregorio]

This looks like a good start.

Thanks,
-joe

--
Joe Gregorio http://bitworking.org

[Ernest Prabhakar]

Hi Benoit,

http://microformats.org/wiki/rest/json

On Sep 2, 2008, at 1:29 PM, Benoît Fleury wrote:

just a few questions/comments regarding this list of requirements.

 * R1: what do you mean by compatible? How to evaluate the compatibility? Do you have example of REST clients?

I don't have any specific in mind; I'm collecting examples under "Implementations"

 * R2: I think a detailed scenario of partial update would help to understand the consequences of this requirement

Great suggestion! Are you volunteering? :-)

 * R4+R5: Doesn't the requirement 5 answers to the requirement 4? Use explicit URIs to link resources? Did I misunderstood one of the requirement?

True, #5 is a superset of #4.  However, my point is that #4 is a higher priority, since it is pretty straightforward, while it is unclear how complex #5 would become.

 * R5: too vague for me. It could be a list of "RPC patterns" to avoid.

I assume you mean R6.  Yes, a more specific statement would be good, but I was just capturing what I heard on the list.

I did add a link to give some context:

http://hideoustriumph.wordpress.com/2008/05/05/ws-deathstar-for-the-rest-of-us/

Thanks for the feedback!

-- Ernie P.

[Nikunj Mehta]

Excellent start. Only problem I see is that the methods do not allow
for searching/querying. If you see GData and OpenSocial, these
indicate that mere CRUD is not enough; there is also the need for
CqRUD, where q stands for query.

On Sep 2, 12:57 pm, Ernest Prabhakar <ernest.prabha...@gmail.com>
wrote:

[Ernest Prabhakar]

Hi Nikunj,

On Sep 12, 2008, at 5:08 PM, Nikunj Mehta wrote:
> Excellent start. Only problem I see is that the methods do not allow
> for searching/querying. If you see GData and OpenSocial, these
> indicate that mere CRUD is not enough; there is also the need for
> CqRUD, where q stands for query.

Good suggestion. I've added "queries":

http://microformats.org/wiki/rest/json#Charter

-enp

[Kris Zyp]

I believe JSONPath (http://goessner.net/articles/JsonPath/) provides a great
foundation for RESTful JSON querying. I have extended JSONPath to have more
comprehensive querying capabilities and more definite, secure, but flexible
syntax that is more compatible with URL query parameter syntax with
JSONQuery. I would propose JSONQuery as the basis for the query format for
RESTful JSON:
http://www.sitepen.com/blog/2008/07/16/jsonquery-data-querying-beyond-jsonpath/.
JSONQuery is designed to easily integrate with URLs by simple postpending of
queries to collection URLs (replacing the $ with the collection URL). For
example:
GET /Book/[?price < 15 & author='Joe'][\rating]This would return all the
books that I 'Joe' authored under 15, and sorted by rating in descending
order (obviously there are characters that should be escaped that I didn't
do).

I didn't include this in the JSON resources proposal because I considered it
an orthogonal concern. I like separation of concerns, but I guess this group
is pretty ambitious ;).
Thanks,
Kris

----- Original Message -----
From: "Ernest Prabhakar" <ernest.p...@gmail.com>
To: <restfu...@googlegroups.com>

[Ernest Prabhakar]

Hi Kris,

On Sep 12, 2008, at 9:58 PM, Kris Zyp wrote:
> would propose JSONQuery as the basis for the query format for
> RESTful JSON:

I've added JSON Path and Query to the charter:

http://microformats.org/wiki/rest/json#Proposals

Thanks!

-- Ernie P.