THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
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 | POSTParameters: ?token=API_TOKEN | |||
api/sessions/SESSIONID | DELETEor | |||||
| GET | |||||
| api/users/USERID/messages | GET | (get USERID from api/session) | api/users/USERID/messages | GET | (long-poll?) should support/encourage a stream-based interface |
api/users/USERID/followees | GET | |||||
api/users/USERID/followers | GET | |||||
api/users/USERID/followees/USERID2USERID | POST,DELETE | 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 | ||||
,POST | ||||||
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 | POST | Parameters: ?name=NAME&test=TEST&action=ACTION | ||||
,POST | ||||||
api/users/USERID/actions/ACTIONID | PUTParameters: ?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 | GETGets a particular message. ,PUT?,DELETE? | |||||
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 | 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/tags/TAGID | GET | Gets the information about a particular tag | ||||
api/conversations/CONVERSATIONID | GET |
One point to note is that most many HTTP clients do not currently support the "PUT" or "DELETE" methods, so these may 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.
...
- ESME API instance (api/)
- Sessions (api/sessions)
- Users (api/users)
- Messages posted by a user (api/users/USERID/messages) (1)
- 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) (1)
- Tags (api/tags) (1)
- Conversations (api/conversations) (1)
- Pools (api/pools) (1)
- ?
- Searches ?? (1)
- Trends ??
(1) Stream interface should be available and use should be encouraged
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.
...
- Is the use of HTTP sessions necessary? Is it desirable?
- Request signing methods?
- Payload and response schemas must be defined
- Should API contain admin functions?
- Webhooks (http://blog.webhooks.org/)
- ESME has webhooks as part of its actions framework, but we may want to document their existence as part of the API, and possibly improve the functionality if there are use cases (http://incubator.apache.org/esme/actions.html)
- What is a conversation?
- Authorization approach (see above)