...
Methods, Resources, and Descriptions
Resource | MethodResource | Description/Payload schema/Response schema | GET|
---|---|---|---|
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.)POST | |
api/sessions | POST | Parameters: ?token=API_TOKEN | |
DELETE | api/sessions/SESSIONID | DELETE | or |
api/users | GET |
| |
api/users/USERID/messages | GET | (get USERID from api/session) GET | |
api/users/USERID/messages | GET | (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
...
/
...
...
GET
...
users/USERID/followees
...
|GET| |
api/users/USERID/followers | GET | POST | |||
api/users/USERID/followees/USERID2 | POST | or POST api/users/USERID/followees?user=USERID2 DELETE | |||
api/users/USERID/followees/USERID2 | DELETE | 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.) | |||
/USERID/tracks | GET | GET | |||
api/users/USERID/tracks | POST | api/users/USERID/tracksParameters: ?track=TEXT_TO_TRACK |
| ||
DELETE | api/users/USERID/tracks/TRACKID |
| GET | api/conversations/CONVERSATIONID DELETE | GET |
api/users/USERID/actions | GET | (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 | POST |
| |||
PUT | 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.) | ||
DELETE | 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.
...