CiviCRM Community Forums (archive)

1. so we had asked for feedback on api usage a few months back and got a minimal response. we assumed (rightly) that not too many people were using it. However there is a small group of folks using it, who failed to give us feedback.

2. internally we call BAO functions in most places instead of the API. We also replaced all internal calls to CRM_Contact_BAO_Contact::createProfileContact and stopped using crm_create_contact. due to schema changes etc, we decided not to upgrade the api (see reason 1 above)

3. It is a bit hard for us to write and test api code since we are not users of the api AND we dont get feedback from the community. Going forward we need to address both points

4. your best bet in 2.0 is to port the 1.9 code over. The 2.0 schema is simpler but similar to 1.9, so the porting task might not to too hard

lobo

lobo

walt:

All of us do agreee with you on the goals and rationale behind an API. However, when we did ask folks how they are using the API and some use cases, we got very few (zero??) replies. This was when we had the mailing list (9 months ago).

I think for us internally the BAO functions serve as a pretty good API. We need to do a better job documenting them, making them consistent and exposing them so folks can start using it. I suspect we'll take this on as a project in 2.2 or so

lobo

Hi,

I think that's a good idea indeed to get rid of the api, that are mostly for what I've seen a very think layer around the BAO calls anyway

My feeling about the documentation is that you have good simple examples and more importantly up to date in the tests, but these should be better promoted (generating doc automatically from them ?)

Last but not the least, no matter how few responses you get, if you change an api or anything public, the release note should mention that in red blinking. That's more than painful to update, have a running new version and to realise that the apis have changed when the end users scream because the custom function developed on the top of the apis don't work anymore

X+

This may be an inappropriate place for the discussion, but since it was mentioned and I came across it: I vote for keeping the API.

The internals of CiviCRM are very confusing to me. I do not have a background in computer science, object oriented programming, etc.. The bulk of my experience is the Drupal context which has a heavy emphasis on clean and relatively easy to use and well documented API functions. There are several developers I've run into in the last year in the Twin Cities (Minnesota) area who have done CiviCRM work and now want to avoid it due to the multiple layers of abstraction of the internal programming and perceived resulting density (also Drupal-oriented developers).

However, I like CiviCRM and I have found the API to be useful and something I am capable of figuring out. The Drupal modules that integrate with CiviCRM that I've used all use the API - I think that's an indicator that the API is being used. I don't think it's too much of a leap to say that many Drupal-oriented developers will prefer the API to figuring out the internal objects/classes/methods of CiviCRM.

There are quirks about the API that can pose challenges, but overall I think it's mostly aimed in the right direction as-is.

My vote would be for keeping the API able, stable and available (sorry, couldn't resist) where possible. I'm with greenmachine - the API should offer us a clean method of interacting with CiviCRM, and one which allows the developer to remain ignorant of the inner workings of CiviCRM specifically.

Not that understanding CiviCRM is a bad thing (not at all) but IMO this is a primary reason for using a published interface rather than interacting directly with internals. If CiviCRM decided in future to change the use of internal methods significantly, the API could maintain a compatible interface for older code. I think this offers advantages for both third party devs AND the CiviCRM team, for whom a published API offers the freedom to change internal code without such repercussions.

If CiviCRM chooses instead to publish documented approaches for using internal methods, that's fine too - but currently the docs tend to encourage use of the API, so that's the approach we've preferred to date.

We've been bitten somewhat by the API changes also during 1.9 - 2.0 migration - especially when some API code was removed from 2.0 after the early developer releases of that version. That said, I was really delighted with how helpful the CiviCRM team were in getting us up and running again, using either the v2 API or the internal code.

But I'd prefer if the API could have stayed stable to start with : )

@dharmatech - nice patch. I had worked around the same problem by using first civicrm_contact_add(), then civicrm_location_add(), but I'd be glad to see this process simplified back to how it worked in 1.x.

We do agree that the API is important. We also feel that the community needs to step up and help play a lead role with the design, development, documentation, testing, maintainance of this. My post: http://forum.civicrm.org/index.php/topic,3400.msg18013.html#msg18013 did not get any volunteers. Folks might also want to read: http://www.dogstar.org/drupal/node/450 to get a better idea on how to effectively contribute to open source projects. Its a bit disheartening that folks will complain about the API but not step up and help

I think you can base phone creation similar to address creation. You just need to pass in the phone fields

lobo