Rethinking CiviCRM API ...

Over the past few releases we've been having quite a few people use and exercise the api. We are getting to the stage where people want to use the api to integrate with other applications (e.g. integration with Thunderbird). Our current API has a few issues. Firstly it was designed and implemented very early on (CiviCRM v1.0) and we've learned quite a bit since then. We decided to use PHP class objects in the API, which in retrospect was a mistake. Secondly, some of the api calls (crm_get_contact) are very heavy and return fairly complex objects. Other api calls expect the same object (crm_add_group_contact) to be passed back in. Finally, the api is exclusively SOAP which is a barrier for a few people. I think it might be a good idea to come out with a simplified api that addresses the above issues in the next release of CiviCRM (i.e. v1.7). For this version our goals are:

• Keep the api simple and lightweight.
• All parameters are basic types:number, strings and arrays.
• Have the ability to return results in JSON, useful for ajax based apps.
• Have a REST interface in addition to a SOAP interface.
• Have a consistent naming scheming, i.e. civicrm_OBJECT_OPERATION (e.g. civicrm_contact_get, civicrm_group_add etc)

We need to also figure out what we expose via the API. Ideally, you want to expose most of the objects and operations on those objects. However, this introduces a fair amount of code and redundancy, and a lot of data translation and validation between the API and the objects it retrieves / updates. I suspect we'll work with the folks using the API closely and introduce things on a incremental basis.

Comments

I like where your thoughts are headed on this.

We kept most of that logic, pushed the normalisation work further and are now using the api v3

 

http://civicrm.org/API_version_3