It seems like time to give people a quick update as to what api v3 is about. API v3 will be shipping with CiviCRM 3.4 and basically it's like v2 but more so. Well, it's like bits of v2 api and all the other bits have been changed to be like those bits... make sense?
The key to v3 is standardisation. All the api have files now represent their entity (which is generally their table name) - membershipContributionLink is now called MembershipPayment. The mismash of things in the UFGroup (or whatever it was) have been split out into UFField, UFGroup, UFJoin, UFMatch (who knew we had an api call that could return a contact's user_id & vice versa?). We're not 100% there on everything but we've made a big step forwards. Some api that I couldn't make sense of haven't been brought across at this stage (volunteers welcome) - the civicrm_uf_profile_groups_ functions spring to mind.
The functions in each api are now all called
Get
Create
Delete
(there is also a shadow 'modify' function which is a wrapper for 'Get then Create' - bearing in mind that 'Create will update if you pass in the relevant id field.)
The new wrapper function can be used (and should be) to call the api functions e.g.
require_once 'api/api.php';
$result = civicrm_api( 'activity','create',$params );
We have also standardised the outputs to be much more predictable. Any success call should now return
'id' (if only one)
'count'
'is_error'
'values' - array of ID indexed values OR sequentially indexed if you prefer (pass in $params['sequential']=1 to get this)
Take a look in the examples directory to get a feel for them
http://svn.civicrm.org/civicrm/branches/trunk.api/api/v3/examples
Or browse the documentation
http://api.civicrm.org/v3/
There are more cool things that Xavier will blog about soon but I thought it was time to get something out about what to expect in the hope of a few more blogs to come.
api v2 will also ship with 3.4 and you may need to add a variable to your civicrm.settings.php to ensure your site continues to use it if you haven't updated your code
Warm beer still available to anyone who wants to pitch in!
Comments
Standardization will be sooooo nice. You wouldn't believe how difficult it is to try to maintain a Drupal module to integrate with any version of CiviCRM from 2.0-3.3.
A big incentive of the v3 was to stop our own pain ;)
This being said, as we are introducing it in the 3.3/4, won't solve the problems with 2.0-3.3
Eileen, thanks for all the work you and the rest of the team has put in to this!
Just trying to get my head around what you have done...is there now supposed to be a set of standard api calls (get, create, delete, modify) for every BAO object?
Is there a test suite for this? The examples directory is almost good for that.
Is it deliberate to require changes for backward (in-)compatiblity? Not sure if that is the best approach.
Should we be upgrading the REST api so that it accesses the v3 api?
Yes, each is BAO/DAO Object (Entity) should have get, create and delete. The format of what they return is similar (eg. on get you get count and values that contains the array of entities)
We introduced some entities that aren't BAO eg civicrm_entity_get that returns the list of entities that are handled by the api.
Yeap, big test suite in api/v3 (merging right now from api.trunk).
We didn't seek for change for the sake of it, but when the v2 happy wasn't coherent, we did fix it, hence the incompatible.
I'll write an article about it really soon, but you can still set on a per request basis if you want version 2 or 3.
You should definitely migrate the REST to the v3, we are going to keep the v2 in parallel for the 3.4/4, but we will definitely drop the v2 at one point or another.
Beside, that's so much more enjoyable to work on the v3... Not to mention the civicrm/ajax/doc that I'm going to present soon ;)
The examples directory is generated by the tests - look in
http://svn.civicrm.org/civicrm/trunk/tests/phpunit/api
The test coverage is not complete but the main 'Create' 'Get' or Delete function in each test outputs to create an example in that directory. A couple of the creates are also being directly testes (which was the original idea) but we still need to put some thought into getting the test suite coverage up.
Not all BAO have an api yet but in theory they will.