Almanac REST Api

General specification for the Almanac REST API

1. all api's will have versioned url ex::

GET /APP01/someobject/

returns the APP api version 01 representation of the object. This way we can expand the api without breaking old code unduly.

2. I recommend doing a bare bone atom implementation and supplmenting

it with JSON representation of individual objects. APP will focus on feeds, JSON will any necessary single object representations (if needed at all).

General Structure

Feeds and containment follow the following hierarchy::

  • Application
  • Almanac
  • Story
  • Comment
  • Comment (reply) [essentially recursive]

For each node in the hierarchy, the api works as such::

  • GET /APP{version}/${node-name}/

returns an atom feed of sub-nodes (not required at first)

  • POST /APP{version}/${node-name}/

Create an almanac

  • GET /JSON{version}/${node-name}/

returns a json representation of the node

  • PUT | DELETE /APP{version}/${node-name}/

modify/delete node

We'll implement just the part of api we currently need (iow, the application is unlikely to need a full rest api, perhaps just a feed of almanacs)

Collections

Any request for a collection (ie a feed), can take parameters for spatial and content filtering::

# need to get input from tschaub

Comments

Unsure of whether threading comments is important, but it is easy to represent replies as feeds and thereby create threading.