Confirmed users
98
edits
Raindrop/WebApis/inflow: Difference between revisions
Jump to navigation
Jump to search
fix heading levels
(add details about 'contacts' API) |
(fix heading levels) |
||
| Line 18: | Line 18: | ||
* '''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. | * '''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. | The 'conversations' namespace is used to access information regarding complete conversations. | ||
=== by_id method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/conversations/by_id''' | Inflow API entry point: '''/raindrop/_api/inflow/conversations/by_id''' | ||
| Line 28: | Line 28: | ||
Fetches and returns a single [[#Conversation object]]. | Fetches and returns a single [[#Conversation object]]. | ||
==== Request Params ==== | |||
* '''key''': The key for a conversation. See [[#Common Request Parameters]]. | * '''key''': The key for a conversation. See [[#Common Request Parameters]]. | ||
| Line 34: | Line 34: | ||
* '''schemas''': 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. | 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''' | Inflow API entry point: '''/raindrop/_api/inflow/conversations/with_messages''' | ||
| Line 45: | Line 45: | ||
Fetches all conversations which include the specified messages. | Fetches all conversations which include the specified messages. | ||
==== Request Params ==== | |||
* '''keys''': The message IDs to search for - see [[#Common Request Parameters]]. | * '''keys''': The message IDs to search for - see [[#Common Request Parameters]]. | ||
| Line 51: | Line 51: | ||
* '''schemas''': See [[#Common Request Parameters]] | * '''schemas''': See [[#Common Request Parameters]] | ||
==== Response ==== | |||
The response is an array of [[#Conversation object]]s. | The response is an array of [[#Conversation object]]s. | ||
=== '''contact''' method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/conversations/contact''' | Inflow API entry point: '''/raindrop/_api/inflow/conversations/contact''' | ||
Fetches all conversations which include a message to or from the specified contact. | Fetches all conversations which include a message to or from the specified contact. | ||
==== Request Parameters ==== | |||
* '''id''': The contact ID. | * '''id''': The contact ID. | ||
* '''limit''': The maximum number of conversations to return. | * '''limit''': The maximum number of conversations to return. | ||
| Line 67: | Line 67: | ||
* '''schemas''': See [[#Common Request Parameters]] | * '''schemas''': See [[#Common Request Parameters]] | ||
==== Response ==== | |||
The response is an array of [[#Conversation object]]s. | The response is an array of [[#Conversation object]]s. | ||
=== '''identities''' method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/conversations/identities''' | Inflow API entry point: '''/raindrop/_api/inflow/conversations/identities''' | ||
Fetches all conversations which include a message to or from the specified identities. | Fetches all conversations which include a message to or from the specified identities. | ||
==== Request Parameters ==== | |||
* '''ids''': An array of identity IDs. | * '''ids''': An array of identity IDs. | ||
* '''limit''': The maximum number of conversations to return. | * '''limit''': The maximum number of conversations to return. | ||
| Line 82: | Line 82: | ||
* '''schemas''': See [[#Common Request Parameters]] | * '''schemas''': See [[#Common Request Parameters]] | ||
==== Response ==== | |||
The response is an array of [[#Conversation object]]s. | The response is an array of [[#Conversation object]]s. | ||
=== '''in_groups''' method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/conversations/in_groups''' | Inflow API entry point: '''/raindrop/_api/inflow/conversations/in_groups''' | ||
Fetches all conversations which are in the specified groups. | Fetches all conversations which are in the specified groups. | ||
==== Request Parameters ==== | |||
* '''keys''': An array of grouping identifiers. | * '''keys''': An array of grouping identifiers. | ||
* '''limit''': The maximum number of conversations to return. | * '''limit''': The maximum number of conversations to return. | ||
| Line 98: | Line 98: | ||
* '''schemas''': See [[#Common Request Parameters]] | * '''schemas''': See [[#Common Request Parameters]] | ||
==== Response ==== | |||
The response is an array of [[#Conversation object]]s. | The response is an array of [[#Conversation object]]s. | ||
== 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. | 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''' | Inflow API entry point: '''/raindrop/_api/inflow/attachments/by_id''' | ||
Fetches and returns one or more [[#Attachment object]]s. | Fetches and returns one or more [[#Attachment object]]s. | ||
==== Request Params ==== | |||
* '''keys''': An array of attachment IDs to fetch. See [[#Common Request Parameters]]. | * '''keys''': An array of attachment IDs to fetch. See [[#Common Request Parameters]]. | ||
* '''limit''': Default = 30: 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. | * '''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 object]]s | The response is an array of [[#Attachment object]]s | ||
== Groupings == | |||
The 'grouping' namespace is used to access information regarding message groupings. | The 'grouping' namespace is used to access information regarding message groupings. | ||
=== summary method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/grouping/summary''' | 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. | 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. | This API call takes no request parameters. | ||
==== Response ==== | |||
The response is an array of 'grouping summary' objects. Each summary object has the following properties: | The response is an array of 'grouping summary' objects. Each summary object has the following properties: | ||
| Line 136: | Line 136: | ||
* '''num_unread''': The total number of 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 | The 'contacts' namespace is used to access information regarding contacts and (indirectly) identities | ||
=== by_name method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/contacts/by_name''' | Inflow API entry point: '''/raindrop/_api/inflow/contacts/by_name''' | ||
Fetches and returns information about one or more contacts by the contact displayName. | 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 | * '''startname''': default=null: The first name to search, or null to start at the start | ||
| Line 151: | Line 151: | ||
* '''skip''': The number of items to skop | * '''skip''': The number of items to skop | ||
==== Response ==== | |||
The response is an array of 'contact' objects. Each object has the following properties: | The response is an array of 'contact' objects. Each object has the following properties: | ||
| Line 158: | Line 158: | ||
* '''displayName''': The contact's display name. | * '''displayName''': The contact's display name. | ||
=== with_identity method === | |||
Inflow API entry point: '''/raindrop/_api/inflow/contacts/with_identity''' | 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. | 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. | * '''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: | 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: | ||
| Line 174: | Line 174: | ||
* '''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. | * '''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. | ||
=== 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: | Many API calls return one or many (ie, an array of) conversation objects. A Conversation object has the following properties: | ||
| Line 191: | Line 191: | ||
* '''messages''': An array of [[#Message object]]s. 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. | * '''messages''': An array of [[#Message object]]s. 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. | A message is represented using an object with the following elements. | ||
| Line 199: | Line 199: | ||
* '''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) | * '''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. | An attachment is represented using an object with the following elements. | ||