Answers.Body: <p>Yes, SE isn't designed to have three questions in one, as this leads to a knotted ball of yarn.</p>
  
  <ol>
  <li>API calls are intended to have unchanging interfaces for the life of that version of the API, once the version is marked as stable. Currently API v2 has been retired, API v3 has long been stable, and API v4 is in development.</li>
  </ol>
  
  <p>The nuance you note is that we can only ensure that the results returned by the API are stable if there is a test. </p>
  
  <p>I should also note that if a bug is discovered, eg incorrect tax calculations, then fixing the bug may result in changes to incorrect return values from APIs. </p>
  
  <ol start="2">
  <li><p>Look through the directory for tests. Note that it can be appropriate to have multiple tests for a single method, and we would love to improve the robustness of the use cases we have tests for.</p></li>
  <li><p>The most appropriate place to add a test to lock-in current behaviour for an API is likely <a href="https://github.com/civicrm/civicrm-core/tree/master/tests" rel="nofollow noreferrer">https://github.com/civicrm/civicrm-core/tree/master/tests</a>, though there are other types of tests in other directories that might be relevant. For a class like CRM_Utils_System_Base, probably add tests under <a href="https://github.com/civicrm/civicrm-core/tree/master/tests/phpunit/CRM/Utils" rel="nofollow noreferrer">https://github.com/civicrm/civicrm-core/tree/master/tests/phpunit/CRM/Utils</a>. In terms of making utility methods like these have the 'first order' status of a public API method, this is probably something that deserves community discussion. For example, it might be that we could document somewhere a list of methods that are considered public and stable perhaps in a wiki or preferably to my mind in a docblock. Or it might be decided for consistency and improved Developer Experience to wrap the relevant utility functions in an API wrapper. Could you raise this issue in the dev channel at <a href="https://chat.civicrm.org" rel="nofollow noreferrer">https://chat.civicrm.org</a> or send a message to civicrm-api@lists.civicrm.org after adding yourself at <a href="https://lists.civicrm.org/lists" rel="nofollow noreferrer">https://lists.civicrm.org/lists</a> ?</p></li>
  </ol>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-01-05T07:55:31.217Z
Answers.Text: there's also some comments by [totten worth noting](https://chat.civicrm.org/civicrm/pl/ed9m5zx36tyg9r1piqzq4zgrkw) in the chat
Answers.UserDisplayName: ErichBSchulz
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-01-05T19:30:09.293Z
Answers.Text: Related to this topic, the extensions working group has an item on its radar about revisiting our extension compatibility paradigm. There are a lot items ahead of this one on our agenda, but the question of "what constitutes the CiviCRM API?" is one with far-reaching tentacles. If you care about this stuff, this may be an interesting space to watch: https://issues.civicrm.org/jira/browse/EXT-15.
Answers.UserDisplayName: universalhandle
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-01-03T17:43:03.107Z
Answers.LastActivityDate: 2017-01-03T17:43:03.107Z
Answers.UserDisplayName: Joe Murray
Body: <p>It's been said, quite reasonably, that all APIs should have tests, and that if a feature doesn't have tests then coders shouldn't rely on it.</p>
  
  <p>This raises <strike>two</strike> three questions:</p>
  
  <ol>
  <li>other than direct "API3" calls what can I rely on not to change in the future?</li>
  <li>how can I know which methods have tests?</li>
  <li>what is the strategy is for introducing new tests to "lock in" certain useful utility methods?</li>
  </ol>
  
  <p>As one small example, specifically I am talking about the "sub-API-API" - eg <a href="https://civicrm.stackexchange.com/questions/16450/best-practice-for-using-core-base-functions-crm-utils-system-base-from-an-exte">these type of methods</a> but also accessing other "system" services (like mail, http, debug logging, UF, UI messenging)</p>
  
  <p>(sorry this maybe a bit wooly for SE, but it is something I have struggled with)</p>
  
Tags: <api><php><coding-standards>
Title: What are the core functions an extension can rely on?
ThreadText: # What are the core functions an extension can rely on?
  
  (Asked by: username_0 on 2017-01-02)
  
  It's been said, quite reasonably, that all APIs should have tests, and that if a feature doesn't have tests then coders shouldn't rely on it.
  
  This raises two three questions:
  
  1. other than direct "API3" calls what can I rely on not to change in the future?
  2. how can I know which methods have tests?
  3. what is the strategy is for introducing new tests to "lock in" certain useful utility methods?
  
  As one small example, specifically I am talking about the "sub-API-API" - eg [these type of methods](https://civicrm.stackexchange.com/questions/16450/best-practice-for-using-core-base-functions-crm-utils-system-base-from-an-exte) but also accessing other "system" services (like mail, http, debug logging, UF, UI messenging)
  
  (sorry this maybe a bit wooly for SE, but it is something I have struggled with)
  
  **Tags:** api, php, coding-standards
  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2017-01-03. Score: 2 | Accepted answer
  
  Yes, SE isn't designed to have three questions in one, as this leads to a knotted ball of yarn.
  
  1. API calls are intended to have unchanging interfaces for the life of that version of the API, once the version is marked as stable. Currently API v2 has been retired, API v3 has long been stable, and API v4 is in development.
  
  The nuance you note is that we can only ensure that the results returned by the API are stable if there is a test.
  
  I should also note that if a bug is discovered, eg incorrect tax calculations, then fixing the bug may result in changes to incorrect return values from APIs.
  
  2. Look through the directory for tests. Note that it can be appropriate to have multiple tests for a single method, and we would love to improve the robustness of the use cases we have tests for.
  3. The most appropriate place to add a test to lock-in current behaviour for an API is likely <https://github.com/civicrm/civicrm-core/tree/master/tests>, though there are other types of tests in other directories that might be relevant. For a class like CRM\_Utils\_System\_Base, probably add tests under <https://github.com/civicrm/civicrm-core/tree/master/tests/phpunit/CRM/Utils>. In terms of making utility methods like these have the 'first order' status of a public API method, this is probably something that deserves community discussion. For example, it might be that we could document somewhere a list of methods that are considered public and stable perhaps in a wiki or preferably to my mind in a docblock. Or it might be decided for consistency and improved Developer Experience to wrap the relevant utility functions in an API wrapper. Could you raise this issue in the dev channel at <https://chat.civicrm.org> or send a message to civicrm-api@lists.civicrm.org after adding yourself at <https://lists.civicrm.org/lists> ?
  
  > **Comments:**
  > **username_0**: there's also some comments by [totten worth noting](https://chat.civicrm.org/civicrm/pl/ed9m5zx36tyg9r1piqzq4zgrkw) in the chat  
  > **username_2**: Related to this topic, the extensions working group has an item on its radar about revisiting our extension compatibility paradigm. There are a lot items ahead of this one on our agenda, but the question of "what constitutes the CiviCRM API?" is one with far-reaching tentacles. If you care about this stuff, this may be an interesting space to watch: https://issues.civicrm.org/jira/browse/EXT-15.  
  
  ---
  
  