= CiviCRM HowTo Use Rest API

Tags: [[CiviCRM]] [[HowTo]]

== Relevant Links for version 4.2

* [[http://book.civicrm.org/developer/current/techniques/api/|Devlopers Guide API Reference]]
* [[http://wiki.civicrm.org/confluence/display/CRMDOC42/API+Reference|API Reference]]
* [[http://wiki.civicrm.org/confluence/display/CRMDOC42/REST+interface|Rest Interface]]
* [[http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=86213627|Setting up a Site Key]] - necessary for Rest API.
* [[http://lcbru-test.xuhl-tr.nhs.uk/civicrm/ajax/doc/api#explorer|Test Server API Explorer]]
* [[http://lcbru-test.xuhl-tr.nhs.uk/civicrm/api/doc|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 [[http://www.thebitmill.com/tools/password.html|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:

{{{#!sql
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 [[http://issues.civicrm.org/jira/browse/CRM-8514?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel|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.

[[BackLinks]]