REST_API_Documantation

ESME REST API
Featured

Updated Feb 4, 2010 by richard....@siemens.com

Note: The ESME API attempts to conform to the design principles of Representational State Transfer (REST).

Status

What's the status of the session

GET /api/status

<esme_api operation="status" success="false"/>
	<esme_api operation="status" success="true">
	<user nickname="..." id="1"/>
</esme_api>

Login

Create a session

POST /api/login

token=API_TOKEN

<esme_api operation="login" success="true"/>

Logout

Destroy current session

GET /api/logout

<esme_api operation="logout" success="true"/>

Get Messages

Gets the 40 most recent messages in the User's mailbox

GET /api/get_msgs

<esme_api operation="get_msgs" success="true">
	<message id="1134" source="web" date="...">
		<author image="..." name="..." id="9"/>
		<body>
			Woohoo - got through the rest of the slides quite quickly. I can go home now.
		</body>
		<tags/>
	</message>
</esme_api>

Wait for Messages

Waits up to 5 minutes for a new message to appear in the User's mailbox... Long Polling

GET /api/wait_for_msgs

<esme_api operation="wait_for_msgs" success="true">
	<message id="1134" source="web" date="...">
		<author image="..." name="..." id="9"/>
		<body>
			Woohoo - got through the rest of the slides quite quickly. I can go home now.
		</body>
		<tags/>
	</message>
</esme_api>

Send Message

Sends a message

POST /api/send_msg

message=messagebody

via=optional_name_of_client

tags=optional_comma_delimitted_tags

metadata=optional_XML_Element_data

replyto=optional_id_of_message

<esme_api operation="send_msg" success="true"/>

Get Following

Gets all the users that the current user is following

GET /api/get_following

<esme_api operation="get_following" success="true">
	<user nickname="ewh" image="..." id="13" whole_name="..."/>
</esme_api>

Get Followers

Gets all the users that follow the current user

GET /api/get_followers

<esme_api operation="get_followers" success="true">
	<user nickname="..." image="..." id="13" whole_name="..."/>
</esme_api>

Follow

Start following another user

POST /api/follow

user=id_of_user

<esme_api operation="follow" success="true"/>

Unfollow

Stop following another user

POST /api/unfollow

user=id_of_user

<esme_api operation="unfollow" success="true"/>

All Users

List all users in the system

GET /api/all_users

<esme_api operation="all_users" success="true">
	<user nickname="..." id="4" whole_name="..."/>
</esme_api>

Get Tag Cloud

Gets the tags and words for the tag cloud

GET /api/get_tagcloud

numTags=optional_no_of_tags

<esme_api operation="get_tagcloud" success="true">
	<tag_cloud>
		<tag name="Scrum" weight="0.33333334"/>
		<word name="meeting" weight="0.13333334"/>
	</tag_cloud>
</esme_api>

Get Tracking

Gets the list of items the user is tracking

GET /api/get_tracking

<esme_api operation="get_tracking" success="true">
	<tracking user="1" removed="true" createdAt="1219639418277" id="1"/>
	<tracking user="1" removed="false" createdAt="1220896384128" pattern="#esme" id="24"/>
</esme_api>

Add Tracking

Adds a tracking item

POST /api/add_tracking

track=text_of_thing_to_track

<esme_api operation="add_tracking" success="true"/>

Remove Tracking

Removes the tracking item

POST /api/remove_tracking

trackid=id_of_tracking_item

<esme_api operation="remove_tracking" success="true"/>

Get Conversation

Gets all the messages in a conversation

GET /api/get_conversation

conversationid=Conversation_id

<esme_api operation="get_conversation" success="true">
	<conversation id="1089">
		<message when="..." date="..." source="Web Dynpro ABAP" id="1089" conversation="1089">
			<author image="..." name="..." id="24"/>
		</message>
	</conversation>
</esme_api>

Get Actions

Gets the actions

GET /api/get_actions

<esme_api operation="get_actions" success="true">
	<action action="resend" enabled="true" name="#0208" test="#o208" id="3"/>
</esme_api>

Add Action

Adds an Action

POST /api/add_action

name=name_of_action

test=test_that_triggers_action

action=action_to_take

<esme_api operation="add_action" success="true"/>

Enable Action

Enables or Disables an Action

POST /api/enable_action

id=action_id

enabled=true|false

<esme_api operation="enable_action" success="true"/>

Delete Action

Deletes an Action

POST /api/delete_action

actionid=action_id

<esme_api operation="delete_action" success="true"/>

Comment by jmettr...@gmail.com, Dec 5, 2008

Hi,

why not something more like :

GET /api/messages => retries a list of messages GET /api/messages/xyz => retrieves a specific message POST /api/messages => to create a new message (returns 201 + Location: and the URI of the created message) ...

Ideally there should be one initial resource linking to all resources...

This current API is more RPC over HTTP than REST : there are many methods and they are mentioned in the URI and in the payload...

To get something RESTful looking at AtomPub? (http://tools.ietf.org/html/rfc5023) for inspiration (or even using it directly...)

Best regards.

Comment by deh...@gmail.com, Dec 20, 2008

This is an RPC API tunneled over HTTP. Why are you calling it "ESME REST API"?

Comment by nextd...@gmail.com, Apr 17, 2009

Not to rant, but...

I agree you could call this an RPC over HTTP protocol and maybe it's not technically REST. But WHO CARES? I've never understood why REST folks are so hard-core about this issue. HTTP has 4 generic methods and a handful of generic status codes, many of which are poorly supported by widely used server and client technologies. Even if the entire vocabulary were all supported completely, it's still damn anemic and will never be syntactically rich enough to directly support a real API without resorting to a custom set of payload arguments and status code meanings. Anyway, whether you call it RPC or REST, it beats the pants off of SOAP for usability.

► Sign in to add a comment