CiviCRM Community Forums (archive)

Now that API v3 has been mostly bedded in & a good number of things have been sorted out the question of how we maintain it is becoming increasingly topical. Maintenance is never much fun as building things :-) & decisions have to be made about what to maintain. So, the question on this thread is very topical.

I have always believed that the primary point of the API is to provide developers with an interface that hardly changes between versions & makes CiviCRM viable to develop against - without worrying that your customisations & integration will break every upgrade.

To me that means not only keeping the API code consistent but buffering developers against CiviCRM core changes (within reason). So, for example with 4.2 coming out one area I noticed was

that the following call ('event','create', array('title' => 'blah', 'payment_processor_id' => 1);

will no longer work due to schema changes (http://issues.civicrm.org/jira/browse/CRM-10297)

Which leaves us with 3 possibilities

1) We add extra functions into the api to handle these things e.g

civicrm_api3_event_create_legacy42(&$params){
// change old format to new format
}

(We could remove the functions over time - or just when we got to v4 api)

2) We let developers deal with the fallout & don't care

3) we document a series of relevant changes each release (much like 1 but on a wiki rather than in code)

4) We document the changes by returning an error (much like #1 & #3 but we rely on the developers noticing it).

Probably there is little difference in effort required between the options but who does it will vary. For example - dealing with developers griping (#2) is likely to be done by whoever deals with the forums.

I strongly believe there where it is obvious what the behaviour would be if the old params are passed in we should support it - #1. But if I'm alone on that then I'm in trouble - it might be like being the only person who believes the dishes need to be washed & put away.

BTW, breaking a test is definitely what I consider a regression that should be handled.

If we break something that wasn't tested, I think we have more giggle room to decide if it's "broken for real or broken on something that wasn't used anyway", as in "you're using an undocumented feature, tough shit if it changes". Hopefully, that's going to be a good incentive to users to add tests in the API.

a few thoughts and comments:

a. IMO, core should not maintain backward compatibility for schema changes. We are fairly aggressive in improving the schema and/or fixing past mistakes. Adding backward compatiblity will make the task a lot harder and increase code size / add conversion stuff etc.

b. IMO, the api team might want to consider maintaining backward compatibility for some changes and not necessarily all changes. Trapping and returning an error for the other changes is a decent option

c. Finally, the question remains as to who does the needed work at the API layer. We can add it to the MIH, but what happens if the MIH does not get fulfilled completely (as is the case with quite a few of the 4.1 MIH's). Ultimately we do need more developers willing to contribute hours / code to make things more complete. Expecting eileen to do it for the api team or the dim-sum team to do it all is not scalable and/or sustainable

my 2 cents

lobo

I have fixed the identified bug - I realised that not to do so would be essentially to declare the api pointless

http://issues.civicrm.org/jira/browse/CRM-10297

However, I need help identifying other schema changes that make affect API users in 4.2

I guess the issue is that my definition of a stable API perhaps goes beyond some other peoples - in that I think it should buffer developers / custom code from any internal changes. The second issue is that I feel writing this buffering should be part of any development - not just part of the API remit.