Ruby Gem for Collection+JSON

[mca]

I learned today that Mark Burns is working on a Ruby gem for
Collection+JSON. He's posted his work on github:
https://github.com/markburns/collection_json/

He also found a typo in an example. the "links" section hs an example
w/ the curly brace out-of-order. I've updated the docs to fix that,
too.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mark Burns]

Hi Mike. I certainly have. I've just tried to reply a few times to this, but something strange is happening with this browser input box. It keeps collapsing the whole thread and losing my message. It's as if some kind of combination of text input is triggering it. Any ideas?

Anyway, I've also just realised that I've bought your book, Mike, a recommendation from Steve Klabnik's recent blog post.

I'll be working my way through that, and working on this gem as I go. It's all very experimental, and I had begun thinking about how

a JS server may be more suitable. I'll certainly be looking at a JS client first for Collection+JSON unless there's already one out there.

OK posting this before I lose this message again.

[mca]

Mark:

I just use email to converse on this list, not sure what's up w/ the UI.

Happy to hear you have the book. Feel free to send me feedback along
the way; proly best to do that directly, tho (not on this list).

If i understand your comment about servers/clients for
Collection+JSON, you definitely need a way to _emit_ CJ from the
server. I actually do that via a transformation layer on my server
implementations. I use C# quite a bit and then have an XSLT layer that
pops out Collection+JSON from XML-based data layer. For my node apps,
I just use Express and EJS to do the same. Any decent templating
library should do the trick w/o problems.

One thing I do have on my "to-do" list is to write a generic
client-side JS processor for Collection+JSON. That would lower the
barrier for entry on teh client side quite a bit.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Mark Burns]

Hi Mike

 

If i understand your comment about servers/clients for
Collection+JSON, you definitely need a way to _emit_ CJ from the
server. I actually do that via a transformation layer on my server
implementations. I use C# quite a bit and then have an XSLT layer that
pops out Collection+JSON from XML-based data layer. For my node apps,
I just use Express and EJS to do the same.  Any decent templating
library should do the trick w/o problems.

My comment was that for a server, it would probably be more straightforward to write

it in JS as there's less transformation going on. You mention that in your book using 

a Node.js, CouchDB and Javascript in the client simplifies things, so I was just 

acknowledging that. 

Anyway, yeah you're right, the first thing I'm tackling with my gem is emitting client-side

CJ from a Ruby server.

Probably would be good to somehow make it rack compatible so it can be used

by Sinatra and Rails, but I'm just thinking that through at the moment.

It might need to be a set of slightly different libraries that work together as it will

be involved in routing/controller type concerns as well as view level representational

concerns.

Some things I've noticed and thinking through in no particular order:

The ideas of templates are the corollary to GET requests for forms in a HTML API.

I think it could make sense if my library has a way to mix-in functionality that makes

it easier to emit a CJ response via a to_json method. However CJ deals with collections

of resources. Which obviously don't map to singular models in an MVC pattern.

So it seems like we need an easy way of generating 'collections' of objects which for a

singular resource 'read' would be like an array with one item. We need an easy way of

setting a default href on the collection and each item. For rails this would follow rails

conventions as default then allow configuration to be easy.

It seems so far that CJ would work well as a decorator in terms of the outputting correctly

formatted JSON.

In terms of handling the CRUD requests at the server end I guess we just need a sensible

parser that validates the CJ format and pulls out the objects in a usable fashion. For rails/sinatra

this could mean putting them into the params hash. Which I guess would make sense

for it to be a rack app. It can also intercept invalid CJ and send the relevant HTTP status and

message back to the client. 

One thing that I am unclear on is the error object. You state that there should only be one for 

each response.

If I think of other APIs then they may well list a set of errors related to validation of a model.

How would you envisage this occurring?

Or is your error object just reflecting the HTTP status and meaning?

If it's the latter, then how would you picture validation errors being represented?
It might be nice to not just have to parse a String in the error message and each implementor

of an API have to come up with their own protocol/parser/generator.

One thing I do have on my "to-do" list is to write a generic
client-side JS processor for Collection+JSON. That would lower the
barrier for entry on teh client side quite a bit.

OK well that will also be on my list too, so do update the list if you start on that.

I'd be interested in hearing your thoughts on how you'd imagine the API for that working.

It could help me conceptualising the server end too. 

Cheers,

Mark