There is nothing fundamentally wrong with JSON (o.k. maybe a *few* things), but with the right structures, it or any format can be completely self-describing. I have found that including a bit of additional metadata in the content helps IMMENSELY for both loosely-coupled and tightly-coupled applications. The more it self-describes the content, the better.
Jim, now that you're on the Neo team, I would like to show you the (domain-specific) REST API we've put around Neo for our application sometime. Might stimulate some thoughts on your work and provide us some valuable feedback as well. We were planning to do a demo for Peter & team sometime next week, so LMK if you're interested and your availability off-list. Cheers, Rick -----Original Message----- From: [email protected] [mailto:[email protected]] On Behalf Of Jim Webber Sent: Thursday, November 18, 2010 9:04 AM To: Neo4j user discussions Subject: [SPAM] Re: [Neo4j] REST Server API Hi Christopher, > Yes I know what you mean, the "{}" are part of the JAX-RS specification. They're part of the URI template specification. JAX-RS uses these URI templates. > The Neo4j Rest server uses HTTP and JSON thats true, but it violates IMHO > some of the REST principles. I think that a technical interface should > contain, if the content is a link, a "well formed" URI. I know that a String > like "GET /node/123/relationships/{dir}/{-list|&|types}" means that there > are optional parameter or something like this. Thats OK for a description in > a Wiki page but not in a returned JSON object. It's OK for both, but I agree that in general I prefer fully formed URIs. We'll need to tweak the response representations to include this. > The String "GET /node/123/relationships/out/KNOWS&LOVES" is used as a > query parameter. If it is used as a parameter for a query it should be a > URL-query parameter. Not necessarily. URIs are opaque, it's only because you're a smart human that you can infer something from a string like that, but a machine can't. > Using "POST /node/123/traverse/{returnType}" I can traverse though the > nodes, where returnType is the definition of the kind of objects I want to > have returned. In the basic REST sense POST is a Insert method where a newly > created ressource will be returned in the Location tag of a HTTP Header. For > me this POST is a GET as well, maybe with some query parameter. Agree with you on that - a traversal is a query and so should be a GET. There was a thread on that a while back if I remember correctly. The API will change in future iterations, this would be one of the changes I'd favour. > If you want to distinguish the returned Types, maybe it is a good idea to > use custom mime types for node, path and relation, if you want to use the > same URI for all. I don't like creating custom mime types, but at the same time I don't like JSON (because it's not a hypermedia format, it doesn't understand links). My preference would be to use Clojure data structures (once the Clojure guys have embedded the URI abstraction in the core), and create a standard media type based on Clojure - but I am a dreamer. In the meantime, I suspect we're stuck with this non-standard use of JSON. Jim PS - Bring on the controversial comments about the REST API, they're good possible requirements for us. PPS - I wrote a book about some of this REST stuff with Savas Parastatidis and Ian Robinson. See: http://restinpractice.com > And to be clear, I like this interface very much :-) > > Christopher > > On Thu, Nov 18, 2010 at 9:53 AM, Jim Webber <[email protected]> wrote: > >> Hi Christopher, >> >>> http://localhost:9999/node/1/relationships/in/{-list|&|types}" >> >> This is a URI template, inviting you to replace the {...} with values of >> your own. In this case it's giving you the opportunity to provide a list of >> ampersand separated types. >> >> Now I believe this URI template syntax is out of date compared to the >> current spec, but I'll have to validate that. >> >> Perhaps it's even worth thinking about designing this out of the REST API >> as we move forwards with Neo4j server. Hmmm.... >> >> Jim >> >> >> >> _______________________________________________ >> Neo4j mailing list >> [email protected] >> https://lists.neo4j.org/mailman/listinfo/user >> > > > > -- > Christopher > twitter: @fakod > blog: http://blog.fakod.eu > _______________________________________________ > Neo4j mailing list > [email protected] > https://lists.neo4j.org/mailman/listinfo/user _______________________________________________ Neo4j mailing list [email protected] https://lists.neo4j.org/mailman/listinfo/user _______________________________________________ Neo4j mailing list [email protected] https://lists.neo4j.org/mailman/listinfo/user
