APIv3 Interfaces¶

APIv3 Deprecation

API version 3 is now deprecated. Version 4 is recommended.

APIv3 has three main interfaces along with the PHP Code that can be used to access the API.

Javascript¶

CiviCRM provides a number of different methods to interact with the API when in javascript code. The most common of these is through the AJAX interface which is usually called using jQuery code. The next most common is through the angular interface with a couple of Node.js interfaces

Javascript AJAX Interface¶

The AJAX interface is one of the more common interfaces used within CiviCRM code. The AJAX interface is most commonly seen when used in javascript code. You can get example AJAX interface code out of the API Explorer as needed.

CRM.api3¶

CRM.api3 is a javascript method produced by CiviCRM as a thin wrapper around a call to http://example.org/civicrm/ajax/rest. The standard format of such an API call can be found under the relevant usage sub-chapter of this documentation.

Tests¶

QUnit tests for CRM.api3 can be found in /tests/qunit/crm-api3.

You can run the tests within a web browser by visiting /civicrm/dev/qunit/civicrm/crm-api3 within a CiviCRM development installation.

Changes¶

The recommended AJAX interface has changed between CiviCRM versions as follows:

version 4.2.x - cj().crmAPI(...)
version 4.3.x - CRM.api(...)
version 4.4.x onwards - CRM.api3()

For details see APIv3 changes.

Javascript AngularJS crmAPI¶

With the advent of AngularJS being introduced into the CiviCRM framework, a service was created crmApi() which is a variant of CRM.api3() for AngularJS. It should be noted that the results are packaged as "promises" by AngularJS. The crmAPI property can be manipulate to mock responses and also the JSON encoder uses angular.toJson() to correctly handle hidden properties. Examples of use are

angular.module('myModule').controller('myController', function(crmApi) {
  crmApi('entity_tag', 'create', {contact_id:123, tag_id:42})
    .then(function(result){
      console.log(result);
    });
});

CiviCRM-CV Node.js binding¶

This is a tool that aims to work locally with Node.js and integrates into Node.js cv commands which allow for the interaction with a local CiviCRM install. For example you could use it to get the first 25 contacts from the database as follows

  var cv = require('civicrm-cv')({mode: 'promise'});
  cv('api contact.get').then(function(result){
    console.log("Found records: " + result.count);
  });

You can also use all of CV commands such as getting the vars used to make connection to the CiviCRM instance and other site metadata as follows

// Lookup the general site metadata. Return the data synchronously (blocking I/O).

var cv = require('civicrm-cv')({mode: 'sync'});
var result = cv('vars:show');
console.log("The Civi database is " + result.CIVI_DB_DSN);
console.log("The CMS database is " + result.CMS_DB_DSN);

More information can be found on the project page

Javascript Node-CiviCRM package¶

Node CiviCRM is a Node.js package which allows for the interaction with a CiviCRM instance from a remote server. This uses the Rest API to communicate to CiviCRM. For example to get the first 25 individuals from the database can be done as follows

var config = {
  server:'http://example.org',
  path:'/sites/all/modules/civicrm/extern/rest.php',
  key:'your key from settings.civicrm.php',
  api_key:'the user key'
};
var crmAPI = require('civicrm')(config);

crmAPI.get ('contact',{contact_type:'Individual',return:'display_name,email,phone'},
  function (result) {
    for (var i in result.values) {
      val = result.values[i];
     console.log(val.id +": "+val.display_name+ " "+val.email+ " "+ val.phone);
    }
  }
);

More information can be found on the project page

REST Interface¶

The CiviCRM API provides REST bindings, enabling remote applications to read and write data.

The REST interface for remote applications is very similar to the AJAX interface for browser-based applications. Both submit API calls to an HTTP end-point. However, for remote applications, you must explicitly deal with formatting and authenticating the HTTP requests.

For more detailed information about how to work with REST API, see:

Smarty API Interface¶

When building smarty templates you might find you may want to do lookups from the database for some reason. This maybe to get most recent contribution or other information from a contact's record if you adding templates on. The format of the Smarty API call is very similar to that of the APIv3 calls.

{crmAPI entity="nameobject" method="namemethod" var="namevariable" extraparam1="aa" extraparam2="bb" sequential="1"}

The format is as follows:

entity - the content you want to fetch, eg. "contact", "activity", "contribution"...
method - get, getcount, search, search_count (it shouldn't be a method that seeks to modify the entity, only to fetch data) - note that search and search_count are deprecated in APIv3
var - the name of the smarty variable you want to assign the result to (eg the list of contacts)
extraparams (optional) - all the other parameters (as many as you want) are simply used directly as the "params" to the api. cf. the example below
sequential (optional) - indicates whether the result array should be indexed sequentially (1,2,3...) or by returned IDs. Although it is optional, the default was '0' in CiviCRM up to version 4.3 and '1' in 4.4 so it is advisable to fix it as desired.
return (optional) - The convention to define the return attributes (return.sort_name return.country...) doesn't work with smarty and is replaced by return="attribute1,attribute2,attribute3.."

For example if you wanted to display a list of contacts

{crmAPI entity='contact' action="get" var="contacts" sequential="0"}
<ul>
{foreach from=$contacts.values item=contact}
<li id="contact_{$contact.contact_id}">{$contact.sort_name}</li>
{/foreach}</ul>

Or if you wanted to display a contacts Activities

{crmAPI entity="activity" action="get" var="activities" contact_id=$contactId sequential="0"}
{foreach from=$activities.values item=activity}
<p>Activity { $activity.subject } is { $activity.status_id } </p>
{/foreach}

You can also use the Smarty print_r to help debug e.g. in the case above you could call {$activities|@print_r}

Using it for a javascript variable¶

Instead of displaying the data directly, you might want to use it to initialise a javascript variable. You can now add it directly to the template wihout needing to use the AJAX interface. Which will produce same result but will take less time and server resources

<script>
var data={crmAPI entity="contact" action="get" contact_type="Individual" ...};
</script>