This new API is the recommended method to Create, Get, Delete or Update any CiviCRM data from your code or an external system. It is much more coherent and easier to use than the api v2.
As of the civicrm 3.4/4 and as already available for your viewing pleasure on sandbox.civicrm.org (login/password demo/demo), we have developed an API explorer and code generator that is shipped with civicrm and will let you use interactively the api directly on your own data.
This tool is using the ajax version and you can either type the url for the API you want, press enter and get the result of your request displayed on the grey box, or use the drop down lists.
This explorer exposes the two main parameters of the API:
Beside showing you the result of each api call in the grey box (by default formated as json, but can also be xml), it also generate the code for the different ways of using the API:
The main difference with the api v2 is that now the entity+action are much more visible instead of being implied in the name of the function, and the recommended way of calling an api in php is now:
$result =civicrm_api ($entity,$action,$params);
eg. to retrieve the students (by default limited to 25)
$params = array ('contact_type'=>'Individual', contact_subtype => 'student', version => 3);
$result = civicrm_api('contact','get',$params);
(another improvment on the api v2, params is by value so you can call civicrm_api('contact','get',array( ...));
result always contain "is_error" (0 if you didn't have any problem), count (the number of results returned), and results (that contains the list of entities).
This api v3 can run in parallel with version 2, that we are going to maintain on 3.4/4. This being said, we are recommending you to migrate your existing modules to the api v3, and certrainely to start any new development with it. On the API explorer tool, you can choose what version of the api you want, so you can compare the result of the two and help you on the migration from your existing code.
If you choose the the action create on the API explorer, it won't directly generate the call as you would get an error about a missing param (obviously, you need to provide some values when you create an entity) but will show you all the available fields for the entity you are trying to create. Click on it and you get the field, fill it and press enter. Voila, if you have is_error=0 in the grey box, it means that you have created it properly.
It's so fast that I have started using it as a poweradmin tool, for instance to create a list of tags or groups.
if you get an error, the error message not, you can simply alter the url and see what parameters are needed (in theory, the ones in bold are mandatory, but isn't 100% correct now). In any case, this discovering process by trial and error is much faster and enjoyable than having to alter your php code and re-run. once you found the right parameters for your action, you can copy paste the code and use it in your application.
It should be noted that it's extremely easy to extend the api if you want to add some funky features: add a Magic.php file under api/v3, create a function civicrm_magic_getpony and voila, you have civicrm_api ("magic","getpony"), the smarty, the ajax, the REST, and it's also directly usable from the api explorer at /civicrm/ajax/doc
We want to push the standardisation further and cover 100% of the entities with at least create get and delete actions.
We also want to be more systematic on the naming of the parameters and always have "id" as a valid parameter for any entity for get, modify, delete. Right now, we still have sometimes entity_id (eg contribution_id), or entity (tag).
We would very much appreciate your help to finish this, to have the v3 as coherent and predictable as possible.
As soon as we get than done, we get the modify action available (and working) for all the entities (the code is there already and does a get+merge the existing params and the ones from the database and save). However to have it working, it needs that each entity get and create api handles the id parameter.
When we started that v3 project with the API team, I doubt that any of us had the vision of such a complete change (nor the size of the task). I'm proud to have been part of that group, and I'd like to thanks specifically Erik & Eileen for their hard work and enlighting discussions.
As for the future, we'd like first to finish that api v3, and we have plenty of new ideas (being able to chain the api calls within the same ajax/REST call, being able to have hooks on the apis...) that are going to be much more easier to add now that we have a sound foundation with this version.