...
Streams vs. Resources
In the design below, all parts of ESME are modeled as resources, in keeping with a RESTful approach. Our streaming resources (also thought of as delta-queue resources) are collections that are only additive. We have defined a general streaming interface that strives to be RESTful while prioritizing the performance benefits of streams.
...
Resource | Method | Description/Payload schema/Response schema | Streaming? | Admin Only? |
---|---|---|---|---|
api2/session | GET,POST,DELETE | Post parameter: token |
| |
api2/users | GET, POST | Post parameters: nickname, password - returns: user created |
| POST |
api2/users/USERID | GET |
|
| |
api2/users/USERID/tokens | GET, POST | Post parameters: description - returns: token created |
| GET, POST |
api2/user/messages | GET,POST | Post parameters: message, via (opt), pool (opt), realm (opt), metadata (opt), tags (opt), replyto (opt) | Yes | |
api2/user/tags/TAG | GET |
|
| |
api2/user/tags/TAG/messages | GET |
| Yes | |
api2/user/followers | GET |
|
| |
api2/user/followees | GET,POST | Post parameter: userId |
| |
api2/user/followees/USERID | DELETE |
|
| |
api2/user/tracks | GET,POST | Post parameter: track (regex) |
| |
api2/user/tracks/TRACKID | GET,DELETE |
|
| |
api2/user/tracks/TRACKID/messages | GET |
| Yes | |
api2/user/actions | GET,POST | Post parameter: name, test, action |
| |
api2/user/actions/ACTIONID | GET,PUT,DELETE | Put parameter: enabled (boolean) |
| |
api2/messages/MESSAGEID | GET |
|
| |
api2/messages | GET,POST |
| Yes | |
api2/conversations/CONVERSATIONID | GET |
|
| |
api2/conversations/CONVERSATIONID/messages | GET,POST |
| Yes | |
api2/pools | GET,POST |
|
| |
api2/pools/POOLID | GET,DELETE |
|
| |
api2/pools/POOLID/users | GET,POST | Post parameters: realm, userId, permission |
| |
api2/pools/POOLID/users/USERID | DELETE |
|
| |
api2/pools/POOLID/messages | GET,POST |
| Yes |
One point to note is that some 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.
...
Note on the call: api2/user/messages (http://esmecloudserverapache.dickhirsch.staxapps.net/api2/user/messages?via=SAPRiver&tag=bob&message=User+')
That call uses "tag", not "tags". Looking at the API2 code, the parameter name needs to be "tags".
When it does work, I think the behavior may be a bit misleading, as tags added using the tags parameter do not necessarily show up in the message at all. So make sure to keep an eye on the tag cloud or go to the page for the specific tag you are trying to add and see if it shows up there.
...
Streams
There are a lot of ways we can model streams and I'm very interested in input here. Options for interfacing to streams that I have seen:
...
Once this interface is implemented where planned for a URL, the "Yes" above in the "Streaming?" column will be bolded.
...
...
...
Streams/Message-queues in ESME and in general
...
Formats
Request formats
Format specification
...