This is the latest version of the API (Application Programming Interface) for CiviCRM. If you are here because you're trying to install an extension that requires this, just install this and you're done!

If you are a developer, read on...

Once installed you can navigate to Support -> Developer -> Api4 Explorer in the menu. This gives a live, interactive code generator in which you can build and test api calls:

The php binding returns an arrayObject. This gives immediate access to the results, plus allows returning additional metadata properties.

$result = \Civi\Api4\Contact::get()->execute();

// you can loop through the results directly
foreach ($result as $contact) {}

// you can just grab the first one
$contact1 = $result->first();

// reindex results on-the-fly (replacement for sequential=1 in v3)
$result->indexBy('id');

// or fetch some metadata about the call
$entity = $result->entity; // "Contact"

We can do the something very similar in javascript thanks to js arrays also being objects:

CRM.api4('Contact', 'get', params).done(function(result) {
  // you can loop through the results
  result.forEach(function(contact, n) {});

  // you can just grab the first one
  var contact1 = result[0];

  // or fetch some metadata about the call
  var entity = result.entity; // "Contact"
});

• Instead of a single $params array, each api action has multiple methods to set various parameters.
• Output is an array with object properties rather than a nested array.
• Use the Update action to update an entity rather than Create with an id.
• Use $result->indexBy('id'); rather than sequential => 0.
• getSingle is gone, use $result->first().
• Custom fields are refered to by name rather than id. E.g. use constituent_information.Most_Important_Issue instead of custom_4.

If your extension creates one or more entities (sql tables with a DAO object) you can expose it to the api simply by creating a class (e.g. \Civi\Api4\MyEntity), and optionally declare permissions, set default values, and add custom actions.

• A series of action classes inherit from the base Action class, e.g. Create.
• Each entity may extend the generic action class to provide extra parameters or functionality.
• Update, Replace and Delete actions extend the Get class allowing them to perform bulk operations.
• The Action class uses the magic __call() method to set, add and get parameters.
• The base action execute() method calls the core civi_api_kernel service runRequest() method. Action objects find their business access objects via V3 API code.
• Each action object has a _run() method that accepts a decorated arrayobject (Result) as a parameter and is accessed by the action's execute() method.
• The get action class uses a Api4SelectQuery object (based on the core SelectQuery object.

Each action object has a $checkPermissions property. This always defaults to TRUE, and for calls from REST it cannot be disabled.

Tests are located in the tests directory (surprise!) To run the entire Api4 test suite go to the api4 extension directory and type phpunit4 from the command line.