Raindrop/WebApis/inflow

From MozillaWiki
Jump to: navigation, search

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

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

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

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

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

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.

Contacts

The 'contacts' namespace is used to access information regarding contacts and (indirectly) identities

recent method

Inflow API entry point: /raindrop/_api/inflow/contacts/recent

Returns recent contacts, where recent is defined as the people who the user has sent messages to recently.

Request Params

  • limit: The maximum number of items to return
  • skip: The number of items to skop

Response

An array of Portable Contacts objects.

frequent method

Inflow API entry point: /raindrop/_api/inflow/contacts/frequent

Returns frequent contacts, where frequent is defined as the people who the user has sent messages to frequently.

Request Params

  • limit: The maximum number of items to return
  • skip: The number of items to skop

Response

An array of Portable Contacts objects.

lookup method

Inflow API entry point: /raindrop/_api/inflow/contacts/lookup

Returns one or more contacts, based on contact ID.

Request Params

  • id: The contact ID to return. Multiple id parameters can be passed to fetch more than one contact.

Response

An array of Portable Contacts objects.

search method

Inflow API entry point: /raindrop/_api/inflow/contacts/search

Returns one or more contacts, based on some search criteria. If no search criteria is given, all contacts are returned in an unspecified order.

Request Params

Fields from the a Portable Contacts API can be used to to search. For the Plural Fields only the value can be specified.

Some commmon ones that are used:

  • displayName: The contact's displayName
  • emails: An comma-separated list of email names that should be used for searching.

For pagination, the following params are allowed:

  • limit: The maximum number of items to return
  • skip: The number of items to skop

Response

An array of Portable Contacts objects.

update method

Inflow API entry point: /raindrop/_api/inflow/contacts/update

Updates a contact's information.

Request Params

A JSON encoded object that follows the Portable Contacts API. It requires the presence of an id property in the object. If there is no id property, it means a new contact is being created, so the create API should be used instead.

Response

The contact ID of the contact that was updated.

create method

Inflow API entry point: /raindrop/_api/inflow/contacts/create

Create a contact's information

Request Params

A JSON encoded object that follows the Portable Contacts API.

Response

The contact ID of the contact that was created.


Older methods

by_name method

Inflow API entry point: /raindrop/_api/inflow/contacts/by_name

Fetches and returns information about one or more contacts by the contact displayName.

Request Params

  • startname: default=null: The first name to search, or null to start at the start
  • endname: default=null: The last name to search, or null for no end.
  • limit: The maximum number of items to return
  • skip: The number of items to skop

Response

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

  • id: The contact ID.
  • displayName: The contact's display name.

with_identity method

Inflow API entry point: /raindrop/_api/inflow/contacts/with_identity

Fetches and returns information about one or more contacts which are associated with the specified identity.

Request Params

  • id: The identity ID for which the contact is desired.

Response

The response is an array of 'contact' objects - usually only one contact will be returned, although occasionally a single identity ID (eg, email address) will be associated with multiple contacts. Each object has the following properties:

  • id: The contact ID.
  • relationship: The relationship between the identity and the contact. For example, if the identity ID specifies a phone number, the relationship might be "home" or "office". If it is an email address, it may be the generic "email", or possibly some other identifier. See the Raindrop/WebApis/model#create_identity_relationships_method for more information.

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.
Retrieved from "https://wiki.mozilla.org/index.php?title=Raindrop/WebApis/inflow&oldid=229043"