Response formats

[David Turner]

For the trip planner, Frank has defined an XML schema for responses.
This looks to me like a pretty good base to build on.

But at least some consumers will prefer a json response to an XML
response.

XML can be converted to non-idiomatic JSON using a convention called
BadgerFish. The problem is that it's ugly -- it translates <x>123</x>
to x : {'$' : '123'}, instead of x : 123.

We can do better. We should be able to write some sort of schema
defining how documents conforming to a given XML schema can be converted
idiomatically to json. This requires human labor to write the
conversion rules, but then the conversion can be done automatically.

I'm thinking something like this (for
http://maps.trimet.org/maps/model/xml/Itinerary.xsd):

<response jc:type="object" success="boolean field">
<date />
<time />
<request jc:type="object">
<url />
<param jc:field_from_attribute="name" />
</request>
<from jc:type="object">
<pos type="object>
<x jc:type="numeric"/>
...
</pos>
<description />
</from>
<itineraries jc:type="list">
<itinerary jc:type="object" id="numeric field" viaRoute="string
field">
...

This would result in a response looking something like:
{'success' : true,
'date' : '10/09/2009',
'time' : '10:22:22',
'request' : {
'url' : 'http://...',
'params' {'Mode' : 'A',
'fromPlace' : 'pdx',
...}
}
'from': {
'pos' : {
'x' : 7666295.0,
...
}
},
'description' : 'PDX (Portland)',
}
'itineraries' : [
{'id' : 1,
'viaRoute': '90',
...
------------------

Does this sound like the right strategy?

[Frank]

Hey Dave,

I agree that JSON is a requirement as a response format. But I also
think that XML has it's place. I'm experimenting now with Jersey
(https://jersey.dev.java.net/), and am starting to believe that this
is the platform of choice for our webservice interface.

In the Jersey world, it seems like the preferred method is to define
data objects as POJOs first, then use JAXB to marshall out XML (or
JSON). So I'm thinking to scrap the .xsd first approach (which in the
XMLBeans world of the current trimet tripplanner, is used to generate
my data POJOs at build time). From there, JAXB will be used by Jersey
to generate a given response. There's a xml/json Jersey example
that's influencing this current line of thinking (and we'll see if it
pans out future once I get beyond the trivial demo program):
http://docs.sun.com/app/docs/doc/820-4867/ggrby?l=en&a=view.

Take care,
Frank

ps, I'm also really liking the GeoJSON format, and look forward to
using GeoJSON geometry objects as part of the response. GeoJSON as
XML isn't too bad either. Here's what GeoJSON points look like in
native JSON vs. converted to XML:

http://maps.trimet.org/rt/ws/V1/vehicles/appID/8EB2B259743166EF7569C6C78/id/57/format/json
vs.
http://maps.trimet.org/rt/ws/V1/vehicles/appID/8EB2B259743166EF7569C6C78/id/57/format/xml

[Brian Ferris]

I'd also endorse the "generate a Java bean and serialize the result to XML or JSON" approach.  It's what I use for the OneBusAway REST API (http://code.google.com/p/onebusaway/wiki/OneBusAwayApiReference) and is pretty straightforward.  There are a number of compelling Java REST libraries/frameworks out there, but I think most of the main contenders will support the concept of serializing Java beans to XML and JSON (and other formats) as appropriate.

Which is to say, I'd define your "schema" for now in terms of Java beans that you will be producing and worry about the specific details of serialization later.

Brian

[David Turner]

Oh, that's exactly what I was looking for!

[Chris Holmes]

>
> ps, I'm also really liking the GeoJSON format, and look forward to
> using GeoJSON geometry objects as part of the response. GeoJSON as
> XML isn't too bad either. Here's what GeoJSON points look like in
> native JSON vs. converted to XML:
>
> http://maps.trimet.org/rt/ws/V1/vehicles/appID/8EB2B259743166EF7569C6C78/id/57/format/json
> vs.
> http://maps.trimet.org/rt/ws/V1/vehicles/appID/8EB2B259743166EF7569C6C78/id/57/format/xml
>

Nick actually coded a Java GeoJSON reader for a training project when he
started TOPP (GeoServer/GeoTools just had a writer, as we just produced
it). Gabriel just spent some time cleaning it up, and we're using it in
another project. Should be useful for the client to send geojson
requests to a java server.

David or Gabriel can point you at the repository, and we should work to
move it to a common area like GeoTools. Though I think it's specific to
a library, so you may code up something special for Jersey - it's a
pretty easy format.

Also, just FYI, GeoServer uses RESTlet for all it's rest api stuff. And
xstream to produce the json or the xml (it handles writing both from the
same model). RESTlet gives you a bit more control, but is also more
work. Jersey at the time was immature, the spec wasn't even done. But
it's probably the right call now.

C

> On Oct 9, 11:08 am, David Turner <nova...@novalis.org> wrote:
>> Does this sound like the right strategy?

--
Chris Holmes
OpenGeo - http://opengeo.org
Expert service straight from the developers.