1. Home
  2. Blogs
  3. Blogs

Deprecating v1 API's

Published
2010-10-15 03:43
Written by
kurund - member of the CiviCRM community - view blog guidelines

As a part of 3.3 release we will be deprecating all v1 api's and if you are still use them, it's a good time to migrate to v2 api's before upgrading to CiviCRM v3.3 release.

 

CiviCRM api v2 were introduced in v2.0. For every v1 api there is equivalent v2 api.

 

Reason for removing v1 api's:

  • Most of the v1 api's are not updated since CiviCRM v2.0, hence few api's might be broken.
  • There is no test coverage for v1 api's.
  • No or non-existing document for most of the v1 api's.

 

Migrating from v1 to v2

You need to find equivalent api in v2 and use that. For eg:

 

v1 code to get CiviCRM contact id using CMS user id:

require_once 'api/UFGroup.php';
$contactID = crm_uf_get_match_id( $ufID );

 

v2 code:

require_once 'api/v2/UFGroup.php';
$contactID = civicrm_uf_match_id_get( $ufID );

 

Documentation of available v2 api's can be found at: http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Public+APIs

There are 500+ test cases for v2 api's: http://tests.dev.civicrm.org/trunk/results/

Filed under
CiviCRM

Comments

I'm pretty sure that if anyone is really stuck they can put v1 APIs in the override location.

 

One thing we have been talking about is encouraging people to use a version param when using the API -i.e.

$params['version'] = '3.0';

 

At the moment this has functional implications for location API but we will look to start deprecating a few things  but may have to have 2 versions of the behaviour e.g.

civicrm_contribution_get will return a maximum of one result & an error if more whereas the standard is that it should work the same as the current search returning one or more results

 

If we can come up with a list of calls that are going out in 3.3, it will help us create tools to find these calls in source.  This is an approach that the Drupal people (who muck with their APIs all the time) have done, which helps them manage new releases.

 

The model here is the Coder module, which can search your code and find old or questionable usage of the API, and tell you what to substite it with.

 

If someone will worry about coming up with the OLD ==> NEW table, others of us can adapt the tools.

Eileen,

We had done some major rework on location api in v3.0, hence to maintain previous behavior / backward compatibility we introduced this version number. So by default it accepts v2.x format for location api, unless you explicitly pass version number.

May be in next release we should change default behavior to v3.0 and deprecate support for 2.x format.