CiviCRM Rest API

Relevant Links for version 4.2

• ​Devlopers Guide API Reference
• ​API Reference
• ​Rest Interface
• ​Setting up a Site Key - necessary for Rest API.
• ​Test Server API Explorer
• ​Parameter list for Test Server - What parameters are available for each entity in the API.

Steps to Enable the Rest API

1. Create a site key
2. Create a user
3. Enable the user to access the REST api

Create a Site Key

1. Go to ​The Bit Mill
2. Select Uppercase, Lowercase, Numbers, Punctuation
3. Set Removals from selection as &=+$?%,/:{}#|'
4. Set length to be 32
5. Edit the CiviCRM Settings file.
   • For the test server this is: uhlbriccsapp04:/var/local/civicrm/drupal/sites/default/civicrm.settings.php

Using the REST API

Authentication

In order to authenticate you need the site key from above and an api_key for your user account.

You have to create an api_key in MySQL using the following script:

update civicrm_contact set api_key='<api-key>' where id='<id>';

It's not straight forward to find the user as the unique_user_id column doesn't contain anything, certainly not the unique id of the user. The sort_name and display_name do, however. They did for me anyway.

Example Request

http://lcbru-test.xuhl-tr.nhs.uk/sites/all/modules/civicrm/extern/rest.php?entity=contact&action=get&json=1&key={site_key}&api_key={api_key}

The rest API can be used with the older syntax of

http://lcbru-test.xuhl-tr.nhs.uk//sites/all/modules/civicrm/extern/rest.php?q=civicrm/contact/get&json=1&key={site_key}&api_key={api_key}

or even

http://lcbru-test.xuhl-tr.nhs.uk//sites/all/modules/civicrm/extern/rest.php?fnName=civicrm/contact/get&json=1&key={site_key}&api_key={api_key}

These alternatives being provided to help muddy the water and add as must extra code and confusion as possible.

Options

Documentation is a bit sketchy about options. Here are a few things that appear to be true.

• The default maximum number of entities returned is 25
• The default maximum can be increased by including &option.limit=nnn in the URL. A limit of zero returns all rows. The parameter rowCount also works (case sensitive). See ​here.
• An starting offset can be provided by including &option.offset=nnn in the URL. The parameter offset on its own also works. ibid.
• Sorting uses &option.sort=fffff where fffff is the name of a field returned in the JSON. The parameter sort can also be used.
• The data returned can be restricted using the parameter &return=f1,f2...etc, where fn is a field returned in the JSON.