(NFC) hook_civicrm_alterApiRoutePermissions - Expand on docblock

diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php
index 5c7324b2b088eb8578000c1de06270de2ad698f3..2c0d1958626fe36ea2832017361b5b3ba72fee3e 100644 (file)
--- a/CRM/Utils/Hook.php
+++ b/CRM/Utils/Hook.php
@@ -2788,6 +2788,22 @@ abstract class CRM_Utils_Hook {
   /**
    * Alter APIv4 route permissions based on the Entity and Action
    *
+   * This is an experimental hook intended to *relax* the requirement
+   * for "access AJAX API" when calling public-oriented APIs.
+   *
+   * Historically, when APIv2/v3 were first exposed to an HTTP interface, using
+   * the HTTP interface required an extra permission "access AJAX API". This is a
+   * broad hedge against security flaws within those API's. In the current APIv4
+   * era, security concerns are often baked into each API, so there is a debate about
+   * whether "access AJAX API" serves a purpose or just makes
+   * administration/development more complicated. (So far, there's more support
+   * for the latter.)
+   *
+   * This hook might foreseeably be abandoned either...
+   *
+   * - if it is found that "access AJAX API" guard is not needed for APIv4.
+   * - if the policy is moved into metadata.
+   *
    * @param array|string $permissions
    * @param string $entity
    * @param string $action