Raindrop/WebApis/inflow

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.

Attachments

The 'attachments' namespace is used to access information regarding message attachments. Attachments are a very broad concept in raindrop - attachments include file attachments, hyper-links parsed from messages, etc.

by_id method

Inflow API entry point: /raindrop/_api/inflow/attachments/by_id

Fetches and returns one or more #Attachment objects.

Request Params

• keys: An array of attachment IDs to fetch. See #Common Request Parameters.
• limit: Default = 30: See #Common Request Parameters
• schemas: The list of schemas to return. There is no default for this parameter - you generally need to enumerate a #Message object's attachments element to find the schemas of interest before making this request.

Response

The response is an array of #Attachment objects

Groupings

The 'grouping' namespace is used to access information regarding message groupings.

summary method

Inflow API entry point: /raindrop/_api/inflow/grouping/summary

Fetches and returns information about one or more groupings. It is expected that applications will call this function to determine all the groupings with unread messages, then use the conversations/in_group end-point to fetch the specific conversations.

Request Params

This API call takes no request parameters.

Response

The response is an array of 'grouping summary' objects. Each summary object has the following properties:

• rd_key: The ID of the grouping.
• unread: An array of conversation IDs for the first 5 conversations in the group with unread messages.
• num_unread: The total number of conversations in the group with unread messages.

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 [[[#Attachment object]] summaries 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. Each attachment will have null as the value for each schema (hence it is referred to as an attachment summary)

Attachment object

An attachment is represented using an object with the following elements.

• id: The raindrop key, or ID of the attachment.
• schemas: A selection of schemas for the attachment. This is itself an object, with each 'key' being the schema ID and the value being either an object holding the schema fields, or null if the object is an attachment summary.