CiviCRM Community Forums (archive)

As part of the API documentation & cleanup project coming out of the recent Dev Camp, I (and hopefully others) are working on standardizing the API for 2.2.3. Our goal is to get it stable and complete enough by 2.3 that we can freeze it for the rest of the 2.x series after that.

In general, when something must be changed to conform to the new API standard (documented here: http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=15401593), we're deprecating the old format but leaving it otherwise intact. However, this isn't always possible. When an API function's name and signature already conform to the standard but its behavior does not, then we have to make a decision between 100% backward compatibility and moving in the right direction for the future.

One such case has already come up in the Contact.php API file (api/v2/Contact.php): The civicrm_contact_get function that was there behaves incorrectly according to the new API standard (specifically the part about merging get and search into the same op where the presence of an id determines whether you're getting or searching). What I've done at this point is add an optional parameter to the function called $deprecated_behavior. By default it is false, but if you pass true there instead (like this: civicrm_contact_get($params, true) then you'll get the old behavior.

I still need to work out how to make the REST interface work with this so you can request deprecated behavior via that. We already discussed adding a version parameter to the REST interface so you could request a specific API version with each call. Maybe that's how we should handle this? I kind of didn't want to create yet another api/vX directory in the source tree, but maybe that's the better solution. What do other folks think?

So if you have code that uses civicrm_contact_get, you'll need to either update it to conform to the new API standard (basically for this, you just need to expect to get an array of contacts back, even if you're just getting one by passing in a contact_id) or else start passing true for the $deprecated_behavior parameter. Obviously the much better path is to conform to the new standard whenever possible since the deprecated behavior will go away in a future release.

If folks think this is an acceptable way to go forward, then we should follow this convention everywhere we encounter a situation where the old function is already using the correct name and signature but we need to alter its behavior. That is, add a 2nd parameter after $params called $deprecated_behavior that dictates which "mode" the function operates in.

On the flip side, it took me a while to find this information.  So far as I can see, it isn't mentioned yet in the API docs. 

That's because we're still working on it. It hasn't been released in any production version of CiviCRM yet. Once it is, you'll see those docs updated.

If you want to help out, we could really use a "prime mover" on this effort. I've been distracted by other $day_job responsibilities, so I've been slack in this role lately. I'd love to return to it soon, but if someone else took up the mantle in the meantime, that would be great. You wouldn't have to understand everything, just know who was involved, who knows what, who is working on what, etc. and bug us until we get things done. I can help you get up to speed in that regard.

Walt,

I agree. That's something we should add to the list of things to standardize. But I'm thinking we could do it by "freezing" the params around the 2.3 (or whatever version gets the first standardized API release) schema and then coding interpretation layers when and if the schema changes down the road so that the API params do not. Does that seem like an OK approach or will it cause us more problems later?

Walt, still waiting to hear details on what API change broke uc_civicrm. If i had to guess, it was more a bug than a schema change

It was Wes's change to conform to the new policy.

disclaimer: most of this does not apply to DT as an org, since you'll are great open source citizens (IMO) and participate/give back

while at some level your response makes sense, at some other levels it does not.

If you treat open source purely as a product it does make complete sense. Unfortunately i dont think folks should treat it purely as a product. We just dont have enough resources etc to keep it moving without a LOT MORE community support. Some examples:

* CiviCRM 2.1 on D5. Lots of folks wanted it. No one was willing to sponsor it or even help work on it. We were willing to assist significantly. Bottom line: talk is cheap, action is a lot more expensive

* D5 -> D6 upgrade. Similar situation to above. Lots of folks want to use D6 but not many folks willing to help pay / upgrade modules. If some/all of them chipped in to help make it happen, i suspect things would have moved faster. However changing the mentality of the herd is a much harder problem

my 2 cents.

lobo

Since the Drupal API has been so successful at drawing community contributions (literally thousands of contributed modules, with more contributed every day), let's look at how they manage their API for whatever lessons we can learn.

When you click on the link above, you see a page with 5 tabs at the top.  Each tab represents one (incompatible) version of the API.  The current (Drupal 6) tab is selected by default.  If you click on, for example, "Module system (Drupal hooks)" you get a page with a list of API calls.   Clicking on, for example, "hook_access" you see that there are actually only two versions of this call, a version for Drupal 4.6-5 and a different version for Drupal 6-7.  The most important feature of this page for me, as a community contributor trying to write code for Drupal, is that the calling sequence and the parameters that may be passed are spelled out in sufficient detail that I can actually program from this information.  Notice also that there are links to examples and related discussions.

Going back to the Drupal API home page, we notice that there is a tab for Drupal 7.  This is the next incompatible API change.  Drupal 7 is expected to be released sometime this Fall, but the API changes have been available for public discussion for months.  This allows developers (well, those developers that plan ahead  ) to prepare for the next release.  For those developers that DON'T plan ahead, they have obviously had plenty of warning so Dries can say "I told you so"  .

So how does this affect us in practice?  Well obviously, each incompatible API version represents a major hurdle to upgrade.  Now that Drupal 6 has been out for over a year, we have: five client sites live on Drupal 6 (plus our own site since we eat our own dogfood), eleven sites live on Drupal 5 and one live on Drupal 4.7.  Some of the Drupal 6 sites were converted from Drupal 5, and there was a significant effort involved in some cases, because of the need to deal with some special situation where a Drupal 5 module wasn't available for Drupal 6.

So that's one very successful example of an API that supports community contributions.  We could do much worse than to imitate it.

-- Walt