h2. Streams vs. Resources

In the design below, all parts of ESME are modeled as resources, in keeping with a RESTful approach. Our streaming resources (also thought of as delta-queue resources) are collections that are only additive. We have defined a general streaming interface that strives to be RESTful while prioritizing the performance benefits of streams.

For background design information, see this [page|ESME:Overall Design Discussions].



h2. Resource/Object/Stream Hierarchy

The above is based on a rough object hierarchy as follows:

* ESME API instance (api2/)
** Session (api2/session)
** Users (api2/users)
*** Specific User (api2/users/USERID)
** Messages posted by logged in user (api2/user/messages) (1)
** Users followed by logged in user (api2/user/followees)
** Users following logged in user (api2/user/followers)
** Trackers belonging to logged in user (api2/user/tracks)
*** Messages from a track (api2/user/tracks/TRACKID/messages) (1)
** Actions belonging to logged in user (api2/user/actions)
** Messages (api2/messages) (1)
** Tags (api2/tags)
*** Messages posted to a tag (api2/tags/TAG/messages) (1)
** Conversations (api2/conversations)
*** Messages posted to a conversation (api2/conversations/CONVERSATIONID/messages) (1)
** Pools (api2/pools)
*** Users associated with a pool (api2/pools/POOLID/users)
*** Messages posted to a pool (api2/pools/POOLID/messages) (1)
** Searches  (1)
** Trends

(1) Stream interface

Each of these bullets represents a set of objects. The resource representing an individual object lives at api/objects/OBJECTID. For example, api/conversations/1. As much as is reasonable, one would expect to be able to GET (read), POST (create), PUT (update/amend), or DELETE (delete) any individual member of each of these object sets. Going through each of these objects to ask what it would mean to create, read, update, or delete that object may reveal holes in the existing API, some of which I have filled in above.