Proposal for change to JSON responses
Ross Singer
that I don't like some of the decisions I've made up until now :)
One of the things Elliot made a good point about last week was that
connector developers shouldn't need to know how their data is going to
be serialized (i.e. they shouldn't need to know whether something will
ultimately be an attribute or a value) and this is essentially how the
connector API was designed (I mean, more towards Elliot's ideal). I
still think a standard syntax needs to be designed for extensions, but
let's table that for a bit.
Right now the connector JSON response is way too deeply tied with Atom
semantics and can be done much simpler.
So here's my proposal.
At the base or "feed" level, every connector response returns the
following keys:
"request": an echo of the incoming request, for confirmation
"time": a timestamp of the response
"totalResults" : the number of resources that match the request, *even
for requests for a specific ID*
"offset": the start index of the results - default "0"
"data": an array of resources (this was the original key name, which
was changed to "entry" -- this is purely a style choice -if people
prefer 'entry', let's just keep that)
optionally, at the feed level there may be the following:
"related": An array of related URIs. Each item in the array must be
a hash with: "type"=mimetype_of_related_feed,
"href"=URI_of_related_feed and, optionally, "title"=title_of_feed
"alternate": An array of alternate representations of the requested
feed. Each item in the array must be a hash that conforms to the
syntax above.
"search": a hash that conforms to the above syntax -- most cases would
be pointing to an opensearch description document.
"extension_namespaces": a hash with the namespace prefix as the the
key and the URI as the value
what these changes would do is:
1) make paging much easier and integrated into the jangle core
2) make opensearch output roughly the same as paging (right now
they're needlessly different)
3) do away with the awkward link hierarchy and just expose the relationships
Also, on the flipside it means:
1) some redundant data for requests for single resources
2) no facility (currently) for other types of link relationships
(namely, "enclosures" and "via")
In the data array, the returned resources themselves should contain:
"id": the _Jangle_ URI of the resource
"updated": ISO 8601 timestamp of the last modification time
"content": the payload of the resource
"content_type": the mime-type of the aforementioned payload
Additionally, an entry *should* have a "title" key although Jangle
core can provide a generic string if none is provided.
Optionally, the entry could have:
"related" and "alternate" formatted as in the feed level.
"summary": a text description of the entry
"created": an ISO 8601 timestamp of the creation date of the resource
(will go in the 'published' tag in Atom)
"category": categories need to be defined in Jangle since they will
help us out of a lot of ambiguity between resources
and, finally:
"author" -- this one is problematic, as it is one of the only Atom
fields with child elements. I have no strong opinions on how to
implement this.
Any opinions or critiques or suggestions or alternatives to this are welcome.
-Ross.
Ross Singer
The feed level needs another key, "type" which corresponds to the
mime-type the response should be serialized as (since it could be an
collection, an atom service document or an opensearch description
document).
-Ross.
Godmar Back
connectors will reply to the core with JSON responses (whose design
you discuss below) transmitted via http; do you have a URL for some
example connectors so we can see what this looks like currently?
- Godmar
Ross Singer
http://connector.jangle.org/actors/
http://connector.jangle.org/actors/1866
http://connector.jangle.org/resources/
http://connector.jangle.org/resources/5878
http://connector.jangle.org/items/
http://connector.jangle.org/items/000006418
http://connector.jangle.org/collections/
http://connector.jangle.org/collections/2
http://connector.jangle.org/collections/2/resources
I don't have the demo running with my proposed changes yet.
-Ross.