Raindrop/WebApis/model

From MozillaWiki
Jump to: navigation, search

Introduction

The model API functions are used for low-level access to the raindrop's "document model". These functions allow you to create raw schema items, open raw schema items, etc. There are also a number of helper functions exposed - in general, these helper functions are also exposed to the back-end extensions, so this API allows external clients to do very similar things to what extensions can do.

schemas

The 'schemas' namespace is used to work with schemas

open method

API entry point: /raindrop/_api/model/schemas/open

Fetches and returns a multiple raindrop raw schemas.

Request Params

  • items: The items to fetch. An array of [rd_key, schema_id] pairs

Response

The response is a list of schemas. The result list is in the same order as the items parameter, with null used for any schemas which do not exist.

The result objects are 'raw' schemas - they include the schema fields, but also various other book-keeping fields (ie, field names starting with 'rd_').

create method

API entry point: /raindrop/_api/model/schemas/create

Creates new schema items.

Request Params

  • items: The schema items to create. Each item must have 'rd_key', 'rd_schema_id' etc fields, and a field named 'items' with the individual schema fields.

This is the same function exposed to back-end extensions as emit_schema_items; each element in 'items' must correspond to the arguments supported by that function (which is to-be-documented)

Response

The response is the raw response from couchdb listing the documents which were updated. As it is possible multiple items will be rolled into the same document, this list doesn't correspond with the input args - it is just the set of couch documents which the entire operation touched.


contacts

The 'contacts' namespace is used for helper functions to work with contacts

create_identity_relationships method

API entry point: /raindrop/_api/model/contacts/create_identity_relationships

Associates a number of identities with a new or existing contact.

Request Params

  • relationships: A list of identity relationships to be established. Each relationship is an [identity_id, relationship_string] pair. The relationship_string can be anything which makes sense for the identity - for example, if the identity ID referred to a phone number, the relationship_string could be simply "phone", or may be "home", "work" etc.
  • contact_properties: The default properties for a contact if a new contact needs to be created. The 'displayName' field in this parameter is also used to match existing contacts.

This function will only create a new contact and use the contact_properties fields if no existing suitable contact can be located. To locate an existing contact, raindrop first searches the specified identities to see if a contact is associated with any them - if so, that contact is used. If not, the displayName of the contact_properties is used to search for a contact, and if found, that contact is used - but the rest of the contact_properties parameter is ignored. If all else fails, a new contact record is created with contact_properties. All identity IDs are then associated with that contact.

Response

The response is the raw couchdb response for the documents which were updated.