This page is meant to start as a conceptual design for a 2nd generation REST API for ESME. The idea is to learn from the discussions around and use of the original REST API.

REST API Design

Streams vs. resources

In the design below, all parts of ESME are modeled as resources, in keeping with a RESTful approach. For things like message streams, this is not an optimal way to model these entities. I'd like to maintain the ability to interface with the full ESME API in a RESTful manner, while also encouraging the use of more optimal interface approaches when this makes sense.

The existing entities called out as resources below that should be available in some manner as streams are:

• Messages (user-specific) api/users/USERID/messages
• Messages api/messages
• Tags (api/tags)
• Conversations (api/conversations)
• Pools (api/pools)
• Searches ??

References -
*Link to REST API 2.0 - Sessions discussion*

Methods, Resources, and Descriptions

...

Formats to be supported

• XML ?
• JSON ?
• ...

Authorization

Currently the ESME REST API uses tokens as the authorization mechanism. A token is used to establish a session and then the session is used to persist the authorization of the API client across the length of the session.

There are a couple of problems with this, though we don't have a better approach at the moment:

1. Sessions are not natively supported in a lot of API programming environments, especially environments that do not have a persistent data-store available to the application.
2. The current API design appears encourage that the token sent to establish the session be sent in the clear over an unencrypted connection.

Points for discussion, resolution, further work

...