APIv4 REST

Overview

CiviCRM APIv4 provides HTTP/REST bindings, enabling remote applications to read and write data.

As you may recall, the APIv4 architecture uses the triplet ($entity, $action, $params), e.g.

$result = civicrm_api4($entity, $action, $params);
$result = civicrm_api4('Contact', 'get', ['limit' => 10]);

A typical APIv4 REST request includes these three elements and an authentication credential. For example:

https://{$website}/civicrm/ajax/api4/{$entity}/{$action}
  ?params={$params}&_authx={$credential}

In the remaining sections, we will examine this formula more closesly - considering more concrete examples and more precise descriptions of each part.

Is APIv4 a REST-ful interface?

HTTP-based APIs are sometimes described as "REST-ful" if they closely follow certain HTTP conventions. CiviCRM APIv4 is more REST-ful than APIv3, but it is not strictly REST-ful.

Never-the-less, it is generally used for reading and writing resource records, and (by tradition) the subsystem is referred to as "REST".

Examples

As we review the structure of an APIv4 REST call, it may help to have a few examples. Here is a representative example:

1: GET https://www.example.org/civicrm/ajax/api4/Contact/get
2:   ?params=%7B%22where%22%3A%5B%5B%22id%22%2C%22%3D%22%2C22%5D%5D%7D
3:   &_authx=ABCD1234

In line 1, we see an end-point (base) URL (https://www.example.org/civicrm/ajax/api4) along with entity and action (Contact/get). Line 2 conveys the specific API data-parameters (encoded as JSON form-data). Line 3 provides the authentication parameters.

Similar elements should appear in any API call, but the content of each can differ. Here is another example:

1: POST https://crm.example.org/civicrm/ajax/api4/OptionGroup/get
2: Authorization: Basic dXNlcjpwYXNz
3: X-Requested-With: XMLHttpRequest
4:
5: %7B%22where%22%3A%5B%5B%22name%22%2C%22%3D%22%2C%22activity_type%22%5D%5D%2C%22limit%22%3A25%2C%22debug%22%3Atrue%7D

Here, we have a different end-point (base) URL (line 1; https://crm.example.org/civicrm/ajax/api4) with a different entity and action (OptionGroup/get). Line 2 shows a different authentication style. The specific API data also differs (line 5).

End-Point URL

All requests should be submitted to the CiviCRM route civicrm/ajax/api4/{ENTITY}/{ACTION}.

Requests are typically submitted with HTTP POST, but read-only operations may use HTTP GET.

Comparison: URLs on Backdrop, Drupal, Joomla, WordPress

On Drupal, Backdrop, and some WordPress deployments, you may access it with a clean URL.

https://example.org/civicrm/ajax/rest

In other deployments, you may need a verbose URL - such as these WordPress and Joomla URLs:

https://wordpress.example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/ajax/rest
https://joomla.example.org/administrator/index.php?option=com_civicrm&task=civicrm/ajax/rest

The civicrm/ajax/rest end-point is frequently used for browser-based API calls ("AJAX"). In newer versions (CiviCRM v5.36+), it can also be used for remote applications.

Stylisitcally, this is similar to APIv4 REST end-point.

Authentication

Every request for APIv4 should include authentication details. These may be submitted in a few forms, such as:

/* HTTP parameter */
?_authx=Bearer+MY_API_KEY
?_authx=Bearer+MY_JSON_WEB_TOKEN
?_authx=Basic+B64(USER:PASS)

/* Civi HTTP header */
X-Civi-Auth: Bearer MY_API_KEY
X-Civi-Auth: Bearer MY_JSON_WEB_TOKEN
X-Civi-Auth: Basic B64(USER:PASS)

/* Conventional HTTP header */
Authorization: Bearer MY_API_KEY
Authorization: Bearer MY_JSON_WEB_TOKEN
Authorization: Basic B64(USER:PASS)

Which authentication forms can I use?

By default, new AuthX deployments are configured to accept:

• Credentials: API keys or JSON Web Tokens (Passwords are not accepted by default.)
• Flows: ?_authx=, X-Civi-Auth:, or Authorization:

The system administrator may enable or disable support for each credential and flow.

Some hosting environments may have compatibility issues with Authorization:. If you need to communicate with several different CiviCRM deployments, then ?_authx= and X-Civi-Auth: may be more reliable.

For API keys and passwords, the user must have the matching permission (authenticate with api key or authenticate with password).

X-Requested-With

To ensure broad compatibility, APIv4 REST clients should set this HTTP header:

X-Requested-With: XMLHttpRequest

The header is not required for all requests, but sometimes it is required, and there is generally no harm to setting it.

For more complete details, see Cross-Site Request Forgery (CSRF) and specifically CSRF: APIv4/APIv4 REST.

Parameters

APIv4 $params are transmitted with JSON and URL encoding. Thus, if the PHP $params are:

['limit' => 10]

Then the equivalent JSON will be:

{"limit":10}

and the URL-encoded JSON will be:

%7B%22limit%22%3A10%7D

Response

The response will be a JSON document. A well-formed response provides a list of values:

{
    "version": 4,
    "count": 10,
    "values": [
        {
            "contact_id": "1",
            "contact_type": "Individual",
            "contact_sub_type": "",
            "display_name": "Example Person",
            ...

Alternatively, if there is an error, then it will be reported with error_message and error_code:

{
  "error_code": 0,
  "error_message": "Api FakeEntity fakeAction version 4 does not exist.",
}

History

• CiviCRM v5.19: Added HTTP bindings for APIv4 to civicrm-core. However, these were only available for browser-based AJAX applications -- not for remote REST applications.

• CiviCRM v5.36: Added the AuthX extension to civicrm-core. This enabled REST-style authentication for APIv4. However, configuring AuthX may require CLI interaction to update hidden settings.

• CiviCRM v5.47: Added the AuthX configuration screen, making it easier for more sysadmins to setup.