CiviCRM Community Forums (archive)

Hi,

On a Skype call those of the API team who were present (the same people who drag ever conversation into a series of poor jokes about warm beer) agreed that the best way to introduce changes that would be difficult to integrate into existing code would be by shipping more than one version of the api. This will see an API folder with subfolders v2 (existing), v3 and v4.

One the top level there will be a function e.g.

function civicrm_contact_get($params){

if (empty($params['version']){
 $params['version'] = 2;
}

require_once 'civicrm/api/v' . $params['version'] . '/Contact.php';
civicrm_contact_get($params);
}

The advantage of this is:
1) This allows us to introduce changes to the API that aren't easily backwards compatible by introducting a new version of the API. For example v2 contribute_get returns an error message if more than one contact is returned which is not compatible with our v3 standard but some code using this API will rely on it
2) Mean that no version 2 code is broken by the introduction of the v3 (&v4) APIs
3) Mean that when people want to change version they only have to change one parameter which means
4) We can be pretty rigid about only supporting the latest version of a given API

The downside is that more code is shipped but we felt better that than break peoples code or try to deal with deprecation by writing complex code.

v3 standard is primarily
1) use correct verbs (create, get, delete)
2) array in / array out
3) $params['version'] is compulsory
4) deprecated functions can GO
5) Test & documentation coverage is at least as good as it is currently

V4 standard is still being determined and v4 standard will be applied to v3 so far as it can be without cause difficulty for existing code

We didn't want to set the bar too high for v3 because there are a bunch of fairly superficial changes (primarily 1 & 2) that can be implemented fairly quickly once we stop having to worry about deprecation and will make it a lot easier to move forward with our more sophisticated wishlist.

SO, having explained ALL that my question is... Can someone suggest a more elegant approach to the function above?

For the beer there is probably a third-party librewery that could be used to avoid re-inventing the barrel.

Just to clarify backwards compatibility when you say "deprecated functions can GO" you are still intending to distribute the old v2 folder with every new release so we can still call a deprecated function with params['version'] = 2, just that if I call it with version=3 then it wouldn't work, right?

I'm thinking that those old functions might continue to call BAO's/DAO's but that nobody is guaranteeing those BAO's to still work the same way? Is that going to cause problems? An alternative would be to offload the compatibility to the API layer, so that if I call it with version=2 the API somehow figures out how to call the current version of the same API call but with the appropriate params and transformations. That can get complicated obviously, but maybe the path of least resistance?

For elegance I might argue to use a more objecty approach but probably doesn't fit in the overall architecture. Using the proposed route where you construct a path based on parameters, from a security standpoint you might want to have some checks. At the least don't allow ".." or path separators in them. And function_exists($function).

So,

I decided to try to get the test suite to work against v3 & hit a problem with versions + Civi + tests.

Civi actually calls the API quite a number of times and every API call is currently hardcoded to v2. The particular example I hit was an obscure API which appears to have been slightly renamed in v3 (unless I did it by accident)

civicrm_activity_processemail

In calling this

function parseMailingObject( &$mail ) in Utils/Mail/Incoming.php gets called which has
        require_once 'api/v2/Activity.php';
which causes a fatal error if you have already loaded (to test)
        'api/v3/Activity.php';

as they have the same functions in them.

In this case neither of the requires in Incoming.php seem to be required from eyeballing the code & commenting them out doesn't seem to trigger any errors
    //require_once 'api/v2/Activity.php';
     //   require_once 'api/v2/Contact.php';


However, it does highlight that we need a plan for upgrading the Core with the new version - possibly by setting a constant & calling each function with it as the version. We'd need to be able to set it & change it in the test suite so we can test 2 versions in the same run


http://wiki.civicrm.org/confluence/display/CRMDOC33/Upgrading+api%27s+from+v1+to+v2