API permissioning

One of the goals of the (ongoing) Bristol code sprint was taking a stab at making the API calls properly permissioned, and I’m happy to report that after two days of very fruitful hacking with Erik and Xavier we’ve landed the crux of it on trunk (to be released as CiviCRM 3.3 later this autumn). For backward compatibility the PHP and Smarty APIs won’t be checking the permissions by default (for now), while the REST and Ajax ones will. This is done by the check_permissions setting in $params – if it’s set and true the permission check is performed, otherwise it’s skipped. Later in the code cycle we’ll also add ACL checks (next to the general permission checks). The civicrm_api_check_permission($api, $params, $throw = false) method located in api/v2/utils.php will either return a predicate whether the given call (with the given params, to be used in the future…) is allowed – or, if $throw is true, actually throw up an Exception if it’s not. An example usage (soon to be applied to most of the API calls) can be seen in civicrm_contact_update():

function civicrm_contact_update($params, …)
{
    // …
    try {
        civicrm_api_check_permission(__FUNCTION__, $params, true);
    } catch (Exception $e) {
        return civicrm_create_error($e->getMessage());
    }
    // …
}

(As __FUNCTION__ gets automagically expanded to the current function’s name, the above should be copy-pastable to most API calls as-is.) You can also take a look at the relevant tests: api_v2_UtilsTest::testCheckPermissionReturn(), api_v2_UtilsTest::testCheckPermissionThrow(), api_v2_UtilsTest::testCheckPermissionSkip(), api_v2_ContactTest::testContactCreationPermissions(), api_v2_ContactTest::testContactUpdatePermissions() and api_v2_EventTest::testEventCreationPermissions() to see how it’s supposed to work.

Comments

Dr Piotr (had to say that)

Did you add permissioning to the Contact GET url? That's the one that has the most impact at the moment (via REST)