Chaining

Each API is handling one API, so if you want to create for instance a "complete" contact, you will have one api.contact.create, one or several api.email.create, one or several api.phone.create... (actually, the contact.create "cheat" a bit and already handle some of the related entities, eg. the primary email or primary phone).

It makes testing easier, but has a negative impact on the performance, especially over REST or ajax, as each api call is a separate http request.

The goal is to enhance the api syntax to be able to handle several api calls chained one after the other. The beside the initial api call, the others need to be able to reference some values returned by the first call (eg being able to use the contact id created first when creating the phone/address/emails)

basic syntax: every key in the param in the form "api.entity.action" is a new api call. Without any other configuration, the chained api calls have an implicit param, the id of the first api call, prefixed with the name of the entity. For instance, if the main api call is contact.create and returns id=42, the other apis will have a param contact_id=42

Simple Chained call

civicrm_api ("Contact","Create", array (

contact_type="Individual",

first_name="John",

last_name="Doe",

api.email.create=array (

  email="john@doe.com",

  is_primary=1,

  on_hold=1,

),

api.phone.create =array (

  location_type_id=1,

  phone="101 32934",

  phone=type_id=1,)));

Simple Chained call with several entities of the same type

If you want to create several chained entities of the same type (eg several emails), the param of the api.entity is an array of array instead of an array. eg:

civicrm_api ("Contact","Create", array (

contact_type="Individual",

first_name="John",

last_name="Doe",

api.email.create= array (

  array (

    email="john@doe.com",

    is_primary=1,

    on_hold=1,

  ), array (

    email="john.doe@compuserve.com",

    is_primary=0,

    on_hold=0,

)

);