REST API
Current (RPC) |
REST |
GET /api/status |
GET api/sessions |
POST /api/login |
POST api/sessions?token=API_TOKEN |
GET /api/logout |
DELETE api/sessions/SESSIONID or |
GET /api/get_msgs |
GET api/users/USERID/messages |
GET /api/wait_for_msgs |
GET api/users/USERID/messages (long-poll?) |
|
GET api/messages/MESSAGEID |
POST /api/send_msg |
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 |
POST api/users/USERID/followees/USERID2 or |
POST /api/unfollow |
DELETE api/users/USERID/followees/USERID2 or |
GET /api/all_users |
GET api/users |
GET /api/get_tagcloud |
GET api/tags |
GET /api/get_tracking |
GET api/users/USERID/tracks |
POST /api/add_tracking |
POST api/users/USERID/tracks?track=TEXT_TO_TRACK |
POST /api/remove_tracking |
DELETE api/users/USERID/tracks/TRACKID |
GET /api/get_conversation |
GET api/conversations/CONVERSATIONID |
GET /api/get_actions |
GET api/users/USERID/actions |
POST /api/add_action |
POST api/users/USERID/actions?name=NAME&test=TEST&action=ACTION |
POST /api/enable_action |
PUT api/users/USERID/actions/ACTIONID?enabled=true|false |
POST /api/delete_action |
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 simulatedthrough POST methods with an extra parameter. I think that because of the close mapping to resource verbs, is worth using these methods inthe specification and defining the simulation method for the entire APIseparately.
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 (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.
2 Comments
Dick Hirsch
I'd like to see REST API method calls for groups
GET api/groups
DELETE api/groups/USERID/GROUPID
POST api/groups/USERID/GROUPID
DELETE api/groups/GROUPID
POST api/groups/GROUPID
You might want to add GroupID to the method call for creating a message as well.
D.
Ethan Jewett
Dick,
In light of recent discussions on the list, maybe we should define using keyword "pools". I'd suggest:
Pools API:
GET api/pools
POST/GET/PUT/DELETE api/pools/POOLID
User pools API (to maintain access assignments?):
GET api/users/USERID/pools
POST/GET/PUT/DELETE api/users/USERID/pools/POOLID
Not sure how it should work.
Ethan