Introduction

In almost all cases of modification or customization of CiviCRM you will need to retrieve, update or create data from the CiviCRM database. Obviously you can do that by either accessing the MySQL database directly in your code, or through the standard CiviCRM BAO functions or even DAO. So why would you then use the API?

The answer is that the API is guaranteed to remain stable between releases, and warn developers well in advance of any changes, whereas using MySQL, BAO or DAO offers no such guarantee.

The API is a standard tool to be known and used by all CiviCRM developers.

Aimed at

(Newbie) CiviCRM developers that have a basic understanding of customizing CiviCRM templates and hooks.

Expected participant level

Participants in this training are expected to be able to do all the learning points from the following buiding blocks:

introduction to the CiviCRM world;
customizing templates;
using the CiviCRM hooks.Participants are expected to have a clean svn install of CiviCRM to play with, and a basic knowledge of the CiviCRM functionality and entities.

Participants are expected to have a clean svn install of CiviCRM to play with.

Learning points

After this building block participants will:

know the different ways of using the API with Smarty, PHP, REST, Ajax/jQuery;
know how to use the API explorer;
know how to use the api class;
know how to use the civicrm_api function;
have used the API in a Smarty exercise;
have used the API in a PHP hook exercise;
have used the API in a REST exercise;
have used the API with Ajax/jQuery.

Trainer preparation

Make sure you have read the general instruction on how to conduct a CiviCRM developer training at

Make sure you have read and are able to show the documentation resources for the API:

the CiviCRM developer guide on http://book.civicrm.org/developer
the API documentation at http://api.civicrm.org/v3/
the wiki for the Public API at http://wiki.civicrm.org/confluence/display/CRMDOC40/CiviCRM+Public+APIs|../../../../../../../../../display/CRMDOC40/CiviCRM+Public+APIs\
the API forum at http://forum.civicrm.org/index.php/board,41.0.html
the IRC channel.

Make sure you know where the examples you want to use are, and are tested on the environment you are using.

Make sure you know where the exercises you want to use are, and that you have instructions on what participants should do.

Make sure you are on site half an hour before the training session starts so you can make sure things like WiFi, flipovers or whiteboards etc. are available.

Examples

There are many examples on how the API can be used in different spots. You can use any of these examples, or create your own specific examples as you want and as you think your specific group requires. Just make sure you know what the example does, and can demonstrate it.

there is an examples directory in the api directory that contains examples on all api’s. You can show them on:## your own local machine## on http://svn.civicrm.org/civicrm/trunk/api/v3/examples/
1. on http://api.civicrm.org/v3/ if you select and API and then click on the ‘Basic example’;
Examples of legacy API (mainly v2) are found on http://wiki.civicrm.org/confluence/display/CRMDOC40/Legacy+Using+CiviCRM+APIs+Code+Snippets|../../../../../../../../../display/CRMDOC40/Legacy+Using+CiviCRM+APIs+Code+Snippets\
You will probably be able to get some examples if you search for civicrm on GitHub or Gitorious, but you will have to do some more digging to see if the API is used there.

Exercises

Ideally the exercises are specific to the needs of your participants in your session. In the ideal world you will be able to get participant input in advance, so you might create some exercises before the session. If you feel confident enough you can always create a few exercises on the fly or as you go along and develop an understanding of the requirements of your group.

However it can also be really nice to have a few exercises ready in advance. You can find these exercises on https://gitorious.org/civicrm-developer-exercises.

API building block