...
Method | Resource | Description/Payload schema/Response schema |
---|---|---|
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/sessions?token=API_TOKEN |
|
DELETE | api/sessions/SESSIONID | or |
GET | api/users/USERID/messages | (get USERID from api/session) |
GET | api/users/USERID/messages | (long-poll?) |
GET | api/messages/MESSAGEID | Gets a particular message. |
POST | api/messages | parameters: ? 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/users/USERID/followees |
|
GET | api/users/USERID/followers |
|
POST | api/users/USERID/followees/USERID2 | or POST api/users/USERID/followees?user=USERID2 |
DELETE | api/users/USERID/followees/USERID2 | or DELETE api/users/USERID/followees?user=USERID2 |
GET | api/users |
|
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/users/USERID/tracks |
|
POST | api/users/USERID/tracks?track=TEXT_TO_TRACK |
|
DELETE | api/users/USERID/tracks/TRACKID |
|
GET | api/conversations/CONVERSATIONID |
|
GET | api/users/USERID/actions | (Actions probably don't make sense outside of the context of a specific user.) |
POST | api/users/USERID/actions?name=NAME&test=TEST&action=ACTION |
|
PUT | api/users/USERID/actions/ACTIONID?enabled=true|false | (This is actually a general outlet to update any attribute of an action, including whether or not it is enabled.) |
DELETE | api/users/USERID/actions/ACTIONID |
|
...
- 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
Formats to be supported
- XML ?
- JSON ?
- ...
Points for discussion, resolution, further work
...