The raindrop 'inflow' application defines its own API based around its requirements. This document describes the API.
Inflow API entry point: /raindrop/_api/inflow
Introduction
The inflow APIs all return JSON responses. In almost all cases, the API requires JSON parameters, meaning simple strings must be quoted and rich objects can be passed as parameters. The inflow API is broken into a number of "namespaces" with each namespace having a number of methods available to it. The namespace and method name are included in the URL, as described below.
Common Request Parameters
There are many request parameters common to many of the end-points. These paramaters are discussed here (but check the documentation for each end-point function to see if they apply to the specific end-point.)
- key: the 'raindrop key', or ID, of an item. Depending on the specific end-point, the key may specify a conversation, message, attachment, identity, etc.
- keys: An array of raindrop keys - see the key parameter above. End-points will generally use either the key or keys parameter.
- message_limit: (integer, default=null): The number of messages to return from the API end-point. If null, no limit is imposed.
- schemas: (list, default=null): An array of schemas to return for each message in the conversation. If null, a default set of schemas is returned - this set is dictated by the rd.ext.core.convo-to-summary extension. As a special case, the value ['*'] (ie, an array of one string element with the value '*') means that all schemas known for the items will be returned. Note that in general, the performance of an end-point is best if null is specified, and worst if ['*'] is specified.
Conversations
The 'conversations' namespace is used to access information regarding complete conversations.
by_id method
Inflow API entry point: /raindrop/_api/inflow/conversations/by_id
Fetches and returns a single conversation object.
Request Params
- key: The key for a conversation. See #common request parameters.
- message_limit: See #common request parameters
- schemas: See #common request parameters
Response
The response is a single #conversation object, with the number of messages returned and their schemas dictated by the request params.
with_messages method
Inflow API entry point: /raindrop/_api/inflow/conversations/with_messages
Fetches all conversations which include the specified messages.
Request Params
- keys: The message IDs to search for - see #common request parameters.
- message_limit: See #common request parameters
- schemas: See #common request parameters
Response
The response is an array of #conversation objects.
contact method
Inflow API entry point: /raindrop/_api/inflow/conversations/contact
Fetches all conversations which include a message to or from the specified contact.
Request Parameters
- id: The contact ID.
- limit: The maximum number of conversations to return.
- skip: The number of conversations to skip.
- message_limit: See #common request parameters
- schemas: See #common request parameters
Response
The response is an array of #conversation objects.
identities method
Inflow API entry point: /raindrop/_api/inflow/conversations/identities
Fetches all conversations which include a message to or from the specified identities.
Request Parameters
- ids: An array of identity IDs.
- limit: The maximum number of conversations to return.
- skip: The number of conversations to skip.
- message_limit: See #common request parameters
- schemas: See #common request parameters
Response
The response is an array of #conversation objects.
in_groups method
Inflow API entry point: /raindrop/_api/inflow/conversations/in_groups
Fetches all conversations which are in the specified groups.
Request Parameters
- keys: An array of grouping identifiers.
- limit: The maximum number of conversations to return.
- skip: The number of conversations to skip.
- message_limit: See #common request parameters
- schemas: See #common request parameters
Response
The response is an array of #conversation objects.
API response objects
Conversation Object
Many API calls return one or many (ie, an array of) conversation objects. A Conversation object has the following properties:
- id: The raindrop key, or ID of the conversation.
- subject: The subject of the conversation. Taken from the first message in the conversation.
- message_ids: An array of all message IDs in the conversation sorted by date.
- unread_ids: An array of all unread message IDs in the conversation sorted by date.
- identities: An array of all identities which take part in the conversation.
- from_display: An array of 'display names' which sent messages in this conversation.
- all_grouping_tags: An array of all grouping tags which apply to all messages in this conversation.
- unread_grouping_tags: An array of all grouping tags which apply to unread messages in this conversation.
- grouping-timestamp: An array of grouping tags and timestamps, used primarily by the other parts of the API implementation.
- messages: An array of #message objects. This will generally not be the full set of messages in the conversation, but a selected set, each with a selected set of schemas. Most API calls have request parameters which determine the list of messages and schemas in this element.
Message Object
A message is represented using an object with the following elements.
- id: The raindrop key, or ID of the message.
- schemas: A selection of schemas for the message. This is itself an object, with each 'key' being the schema ID and the value being an object holding the schema fields.
- attachments: An array of IDs for all 'attachments' in a message. The concept of an attachment is quite broad, so includes things like hyperlinks parsed from the messages. The attachments namespace calls can be used to fetch the details of each attachment.