esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "esjewett@gmail.com" <esjew...@gmail.com>
Subject RESTful ESME API - Design
Date Mon, 16 Feb 2009 13:46:42 GMT
I've shared a document with you called "RESTful ESME API - Design":  
http://docs.google.com/Doc?id=ajc6q3nhgqqd_374dhxctqgs&invite=cjh665s It's  
not an attachment -- it's stored online at Google Docs. To open this  
document, just click the link above. --- Anne and Dick suggested sharing  
this design as a Google Doc for the time being. Please click the following  
link for access to edit the document (requires a Google account). Thanks,  
Ethan
Current (RPC)
REST
GET /api/status
GET api/sessions
(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.)
POST /api/login
token=API_TOKEN
POST api/sessions?token=API_TOKEN
GET /api/logout
DELETE api/sessions/SESSIONID or
DELETE api/sessions?session=SESSIONID
(get SESSIONID from api/sessions)
GET /api/get_msgs
GET api/users/USERID/messages
(get USERID from api/session)
GET /api/wait_for_msgs
GET api/users/USERID/messages (long-poll?)

GET api/messages/MESSAGEID

Gets a particular message.
POST /api/send_msg
message=messagebody
via=optional_name_of_client
tags=optional_comma_delimitted_tags
metadata=optional_XML_Element_data
replyto=optional_id_of_message
POST  
api/messages?message=MESSAGE_BODY&via=CLIENT&tags=TAGS&metadata=XML&replyto=MESSAGEID

PUT api/messages/MESSAGEID (payload the same as POST)

DELETE api/messages/MESSAGEID
GET /api/get_following
GET api/users/USERID/followees
GET /api/get_followers
GET api/users/USERID/followers
POST /api/follow
user=id_of_user
POST api/users/USERID/followees/USERID2 or
POST api/users/USERID/followees?user=USERID2
POST /api/unfollow
user=id_of_user
DELETE api/users/USERID/followees/USERID2 or
DELETE api/users/USERID/followees?user=USERID2
GET /api/all_users
GET api/users
GET /api/get_tagcloud
numTags=optional_no_of_tags
GET api/tags

(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.)
GET /api/get_tracking
GET api/users/USERID/tracks
POST /api/add_tracking
track=text_of_thing_to_track
POST api/users/USERID/tracks?track=TEXT_TO_TRACK
POST /api/remove_tracking
trackid=id_of_tracking_item
DELETE api/users/USERID/tracks/TRACKID
GET /api/get_conversation
conversationid=Conversation_id
GET api/conversations/CONVERSATIONID
GET /api/get_actions
GET api/users/USERID/actions

(Actions probably don't make sense outside of the context of a specific  
user.)
POST /api/add_action
name=name_of_action
test=test_that_triggers_action
action=action_to_take
POST api/users/USERID/actions?name=NAME&test=TEST&action=ACTION
POST /api/enable_action
id=action_id
enabled=true|false
PUT api/users/USERID/actions/ACTIONID?enabled=true|false

(This is actually a general outlet to PUT any attribute of an action,  
including whether or not it is enabled.)
POST /api/delete_action
actionid=action_id
DELETE api/users/USERID/actions/ACTIONID


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.

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)

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 (PUT/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, PUT, or  
delete that object may reveal holes in the existing API, some of which I  
have filled in above.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message