= CiviCRM Rest API

== 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

There is some talk in the documentation about having to log in and then use a session ID to access the REST API.  However, more recent documentation says to just post the username and password with every request.

=== 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.

An example: http://lcbru.xuhl-tr.nhs.uk/civicrm/ajax/rest?fnName=civicrm/contact/get&json=1&key={SITE_KEY}&name={USERNAME}&pass={PASSWORD}