APIs-early draft

List of APIs

See expanded descriptions below. This list is primarily an API description based on the Business Objects of the CRM system. Multiple functions may be wrapped up into the final

Definitions

Get. Grab a specific piece of information.
Load. Create a data object with lots of information that the programmer can manipulate.
Update. Update a specific piece of information or all the information within a recognized data object.
Create. Create new data in the CRM system.
Search. Might be the same as a get or just a get with a heck of a lot more parameters.

Do we need to create different APIs for the different Business Objects (i.e. Individual, Household, Organization)? Or can we treat them all as the generic Contact object?
Can Individuals, Households and Organizations be treated as groups? By asking for the members of a Household, you are simply returning all the contacts related to that household via a relationship?
Do we distinguish group returns and relationship returns with a separate set of APIs for each (i.e. get_group_members (which returns contactIDs for a group ID) is different from get_relationships (which returns all contactIDs and their relationship type for a given contactID)?

Business Entity: Individuals

get individual Allows external systems to get a contactID by matching on name and email fields (perhaps LocalContactID+ExternalSystemID?). Returns contactID if a unique match, returns error if no unique match.
load individual Give CRM a valid individual contactID and receive either the standard vcard field set or the vcard+extended field set (this requires data from the Location entity). _What standard do we use? Vcard http://www.ietf.org/rfc/rfc2426.txt Webdav
update individual Give CRM a contact ID and either a standard or extended field set, CRM overwrites that data in CRM. How do permissions work?* *How does the external system get permission to update data?
create individual Allows external system to create a new individual. What is the minimum field set required to create and individual? (perhaps LocalContactID + ExternalSystemID which would generate a unique key that identifies the contact record in the external system-- this avoids requiring an email address and allows things like cookie-ing users prior to knowing their actual identity-- presupposes any external system must register with CRM)
search individuals All vcard standard fields avaliable as parameters. begs the question of what to do for schema updates?? Perhaps we also need a get_individual_search_parameters? This would allow the external system to figure out what fields are avaliable at any given time

Business Entity: Household

get household(s) Allows external systems to get a list of households for a contactID. Presupposes external systems will always start from the user and would their way to the household or organization information.
getmembers_household Get all the contact IDs associated with the houshold and their relationshiop to the household.
load household External system gives contactID for a valid household and gets the household field set back
update household External system gives contactID plus a valid field set for household. again, how do permissions work?
create household External system provides contactIDs for individuals to be associated with the household, the relationships among contactIDs, and a valid field set, and a household is created. We probably want to split this function up... perhaps create household simply passes a valid field set and gets a contactID back. Relationships have to be set up separately... though it would suck to have a bunch of household records created that have no individuals associated with them. Can we require require a relationship create before the create_household returns a success to the external system?
search

Business Entity: Organization

mirrors households
get organization
getmembers organization
load organization
update organization
create organization
search

It looks like Individual, Household and Organization might be able to be collapsed into a generic contact that might look something like this:

Entity: Contact
get contact External system provides email, gets an contactID for an individual (the personal email address), a household (the email address of the primary household member), an organization (the org's email address) back. need to make sure CRM checks for dupes every time it creates a primary email address for each contact type You might also figure out users based on location information. The external system gets a location ID and then wants to get the contactIDs for that location (voter file applications).
getmembers contact External system provides contactID and gets all the contactIDs associated with the submission and their relationships to the submitted contactIDs. might be the same as load contact members below
load contact Probably don't have this API. Make the external system figure out if it wants load_individual, load_household or load_organization.
load contact members Provide a contactID, get associated contactIDs and their relationship to the original contactID. Would this need to be split into load_household_members and load_organization_members since those two cases might have some additional/special data?
update We probably want to make external systems know what they are updating, so no update_contact
create We definatly want external systems to know what they are creating, so no generic create.
search They should know what they are looking for before they go looking. Might need to figure out if an email address is associated with anything in the CRM system...not sure about that one.

Location

get
load
update
create
search Probably need a pretty robust search for GOTV, voter file data driven applications.

Group

get
getmembers group

Relationships

Activities

APIs required for v1 (CivicSpace release)

All APIs for contact type individual.
Moderate need for Location APIs.
No need for Households, Organizations.

APIs in detail.

Name

##

Description

##

Parameters

##

Returns

##

Usage Example

##