Fwd: [community] Listing indices using REST difficult to deserialize (#159)

[Peter Neubauer]

Guys,
WDYT about changing the index representation to something more
parsing-friendly? It makes sense to me but introduces a breaking
change to the API.

Cheers,

/peter neubauer

Google:neubauer.peter
Skype:peter.neubauer
Phone: +46 704 106975
LinkedIn   http://www.linkedin.com/in/neubauer
Twitter      @peterneubauer

brew install neo4j && neo4j start
heroku addons:add neo4j

---------- Forwarded message ----------
From: unhandled
<reply+i-2689587-0f51b033986751d...@reply.github.com>
Date: Fri, Dec 30, 2011 at 4:59 PM
Subject: [community] Listing indices using REST difficult to deserialize (#159)
To: Neo4j build server <build...@neotechnology.com>

While listing indices, the results are returned in a way that makes it
difficult to deserialize the objects using something like JSON.NET

Instead of :

{
 "favorites" : {
   "template" :
"http://localhost:7474/db/data/index/node/favorites/{key}/{value}",
   "provider" : "lucene",
   "type" : "exact"
 }
}

Maybe something similar to the following would be preferable:

{
 {
 "name": "favorites",
 "properties" : {
   "template" :
"http://localhost:7474/db/data/index/node/favorites/{key}/{value}",
   "provider" : "lucene",
   "type" : "exact"},
 }
}

Having attribute names constant facilitates automatic deserialization.

---
Reply to this email directly or view it on GitHub:
https://github.com/neo4j/community/issues/159

[Jim Webber]

From our point of view, it's a modest change to our JSON producing code and our unit/functional tests.

However as you say, the cost comes from keeping this alive alongside our existing API (for two releases). From memory, I don't think I like playing with our JSON producing code like this - it's very convention based and supporting two conventions might be a right PITA.

But if the folks producing REST client libraries push for it, then we should do it.

So: Max? Josh? Tatham? Andreas? Others?

Jim

[James Thornton]

+1 on that -- right now you have to do client-side hacks to add the name back in.

- James

[Peter Neubauer]

Well,
there are a number of other REST changes that we want to do. IMHO we
should start looking into proper versioning on REST level. Rickard
Öberg, you had a lot of thoughts on this?

IIRC, doing it proper meas that the client drivers have to be aware of
versioning, and we might need to tighter integrate the client drivers
with the core builds ...

Cheers,

/peter neubauer

Google:neubauer.peter
Skype:peter.neubauer
Phone: +46 704 106975
LinkedIn   http://www.linkedin.com/in/neubauer
Twitter      @peterneubauer

brew install neo4j && neo4j start
heroku addons:add neo4j

[Jim Webber]

I'm in favour of versioning within the media type (a la HTML), but that means we need a media type which isn't just application/json.

Jim

[Josh Adell]

James says he has to do some hacks to get it working for him, so
obviously the current way is not ideal for all.

Semantically, the current way doesn't make sense: you're not returning
an object that is composed of multiple index properties, you're
returning an array of index objects. So the outer wrapper as an
object seems awkward. And if the outer wrapper were an array, you'd
have to put the index name in each index object (where it arguably
belongs.) So there's another, slightly more pedantic, reason to change
it.

Maybe a compromise? Keep the current structure to support existing
client code, but repeat the name inside the index object to make it
more semantically correct:

{
"favorites" : {
"name" : "favorites",

"template" : "http://localhost:7474/db/data/index/node/favorites/
{key}/{value}",
"provider" : "lucene",
"type" : "exact"
}
}

I don't know what types of parsing problems others are having, so I
don't know if that makes things better or worse.

-- Josh

[Peter Neubauer]

I think what has been raised from the .NET and other sides is that if the key is the actual name, parsing into frameworks is a bit hindered as the normal convention seems to be to have a predictable key and then a ariable value. I am all for doing this, along with eliminating scalar JSON representations. My main concern is now to have a clean versioning strategy, as I think the main Neo4j versioning scheme is too coarse grained for these changes. They are breaking changes and will occur in all kinds of APIs, both REST, Java, Cypher and others, so I think there needs to be something that is versioning only the REST part and that client drivers are aware of. Maybe even on a per-URI level?

/peter

--