Raindrop/WebApis: Difference between revisions

Raindrop/WebApis (view source)

Revision as of 00:04, 13 November 2009

2,257 bytes added , 13 November 2009

→‎The 'inflow api'

Jrburke

109

edits

@@ Line 57: / Line 57: @@
 == The 'inflow api' ==
-Once consequence of the above discussions is that each application is likely to require its own application specific API.  This section is a place-holder for the API provided by the 'inflow' application.
+One consequence of the above discussions is that each application is likely to require its own application specific API.  This section describes the API associated with the inflow app.
+As of the [[Raindrop/Milestone/Maple|Maple]] milestone there is a start to the server API. Right now it is just focused on conversations, not contacts/identities.
-This describes the (future) API for the 'inflow' application.  The inflow is the test-bed against which our ideas will be pitted.  This needs to grow into a concrete API proposal which can be used by the inflow.
+Inflow API entry point: '''/raindrop/_api/inflow'''
+=== Common GET URL parameters ===
+* '''limit''': the number of most recent messages to retrieve. These most recent messages are then converted to conversations so the actual amount of messages returned (on the list of conversations) can be larger than the amount specified by limit.
+=== Specific API calls ===
+* '''/raindrop/_api/inflow/conversations/home''': Gives most recent direct and group messages as specified by the rd.msg.recip-target schema. If the message is just to you or you are included in a message with other people it will show up in this list.
+* '''/raindrop/_api/inflow/conversations/broadcast''': Gives most recent direct and group messages as specified by the rd.msg.recip-target schema. If it is a mailing list, or some email from a machine instead of a person it will show up in this list.
+* '''/raindrop/_api/inflow/conversations/by_id''' Gives all messages for a given conversation_id. Takes these parameters:
+** '''key''': The conversation_id from a rd.msg.conversation schema. It should be formated as valid JSON (so surrounded by double-quotes) and URL encoded. For instance: %224AF4ABED.1050204%40example.com%22
+=== Conversation Object ===
+All the API calls above return an '''array''' of conversation objects. A Conversation object has the following properties:
+* '''id''': The conversation_id for the conversation. Taken from an rd.msg.conversation schema from the first message in the conversation.
+* '''subject''': The subject of the conversation. Taken from the first message's rd.msg.body's subject property.
+* '''unread''': The number of unread messages in the conversation. Taken from the first message's rd.msg.seen's schema, or the lack of that schema.
+* '''people''': An array of identity_ids that are associated with all the messages. Taken from all the messages, their rd.msg.body schema's from, to, cc or bcc properties.
+* '''messages''': An array of Message objects. The first one in the list is the message that started the conversation.
+=== Message Object ===
+Message objects inside a Conversation object have the following properties:
+* '''schemas''': an object whose properties are the schemas that make up the message. It does not include any "raw" schemas. Example schemas are "rd.msg.body" and "rd.msg.conversation".