This page is meant to start as a conceptual design for a 2nd generation REST API for ESME. The idea is to learn from the discussions around and use of the original REST API.

REST API Design

Methods, Resources, and Descriptions

Resource	Method	Description/Payload schema/Response schema
api/sessions	GET	(It might make sense for this to return only the current session, but in theory it would return all sessions that the current session is allowed to access, so for an administrator, it might return all open sessions. An individual session would be accessed at GET api/sessions/SESSIONID.)
api/sessions	POST	Parameters: ?token=API_TOKEN
api/sessions/SESSIONID	DELETE	or DELETE api/sessions?session=SESSIONID (get SESSIONID from api/sessions)
api/users	GET
api/users/USERID/messages	GET	(get USERID from api/session)
api/users/USERID/messages	GET	(long-poll?)

api/users/USERID/followees|GET| |

api/users/USERID/followers	GET
api/users/USERID/followees/USERID2	POST	or POST api/users/USERID/followees?user=USERID2
api/users/USERID/followees/USERID2	DELETE	or DELETE api/users/USERID/followees?user=USERID2
api/users/USERID/tracks	GET
api/users/USERID/tracks	POST	Parameters: ?track=TEXT_TO_TRACK
api/users/USERID/tracks/TRACKID	DELETE
api/users/USERID/actions	GET	(Actions probably don't make sense outside of the context of a specific user.)
api/users/USERID/actions?name=NAME&test=TEST&action=ACTION	POST
api/users/USERID/actions/ACTIONID	PUT	Parameters: ?enabled=true\|false (This is actually a general outlet to update any attribute of an action, including whether or not it is enabled.)
api/users/USERID/actions/ACTIONID	DELETE
api/messages/MESSAGEID	GET	Gets a particular message.
api/messages	POST	parameters: message=MESSAGE_BODY&via=CLIENT&tags=TAGS&metadata=XML&replyto=MESSAGEID
api/messages/MESSAGEID	PUT	(payload the same as POST)
api/messages/MESSAGEID	DELETE
api/tags	GET	(This doesn't really seem like an appropriate API method. It should really return all of the tags, or user-specific tags (GET api/tags/USERID) and let the front-end decide what to do with it.)
api/conversations/CONVERSATIONID	GET

One point to note is that most HTTP clients do not currently support the "PUT" or "DELETE" methods, so these have to be simulated through POST methods with an extra parameter. I think that because of the close mapping to resource verbs, is worth using these methods in the specification and defining the simulation method for the entire API separately.

Resource/Object Hierarchy

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

ESME API instance (api/)
- Sessions (api/sessions)
- Users (api/users)
  - Messages posted by a user (api/users/USERID/messages)
  - Users followed by a user (api/users/USERID/followees)
  - Users following a user (api/users/USERID/followers)
  - Trackers belonging to a user (api/users/USERID/tracks)
  - Actions belonging to a user (api/users/USERID/actions)
- Messages (api/messages)
- Tags (api/tags)
- Conversations (api/conversations)
- Pools (api/pools)
  - ?
- Searches ??
- Trends ??

Each of these bullets represents a set of objects. The resource representing an individual object lives at api/objects/OBJECTID. For example, api/sessions/SESSIONID. 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.

Formats

Request formats

Format specification

If there is a request body, format should be specified using the Content-Type HTTP header.

Formats to be supported

XML ?
JSON ?
Multi-part Form-encoded ?
Form-encoded

Response formats

Format specification

Format could be specified using the HTTP Accept header - http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

Another option (though not as robust) would be to append the format to the resource request url. For example /api/users/USERID.json