wiki:CiviCRM HowTo Use Rest API

Version 13 (modified by Richard Bramley, 11 years ago) ( diff )

--

CiviCRM Rest API

Relevant Links for version 4.2

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.
Note: See TracWiki for help on using the wiki.