Bug 1620879: Add "apiversion" field to external_services

To help clients determine which version of a webservice
they might be connecting to.

behatnotneeded: Tests to come later

Change-Id: I90abd0d9470cba4ae42ee3a22a6c0629d325f8d2

htdocs/auth/webservice/db/install.xml

@@ -13,6 +13,7 @@
             <FIELD NAME="restrictedusers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" SEQUENCE="false"/>
             <FIELD NAME="tokenusers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" SEQUENCE="false"/>
             <FIELD NAME="component" TYPE="char" LENGTH="100" NOTNULL="false" SEQUENCE="false"/>
+            <FIELD NAME="apiversion" TYPE="int" LENGTH="10" NOTNULL="false" UNSIGNED="true" SEQUENCE="false"/>
             <FIELD NAME="ctime" TYPE="datetime" NOTNULL="true"/>
             <FIELD NAME="mtime" TYPE="datetime" NOTNULL="false"/>
           </FIELDS>

htdocs/auth/webservice/db/upgrade.php

@@ -498,6 +498,14 @@ function xmldb_auth_webservice_upgrade($oldversion=0) {
 
         log_debug('Clearing out "component" field from old example service groups');
         set_field('external_services', 'component', '', 'component', 'webservice');
+
+        log_debug('Add optional "api version" field to external_services');
+        $table = new XMLDBTable('external_services');
+        $field = new XMLDBField('apiversion');
+        $field->setAttributes(XMLDB_TYPE_INTEGER, 10, XMLDB_UNSIGNED, null, null, null, null, null, 'component');
+        if (!field_exists($table, $field)) {
+            add_field($table, $field);
+        }
     }
 
     // sweep for webservice updates everytime

htdocs/webservice/lib.php

@@ -1997,6 +1997,13 @@ function external_reload_component($component, $dir=true) {
                 $dbservice->shortname = $service['shortname'];
                 $update = true;
             }
+            // Optional "apiversion" field, to let webservice clients adapt gracefully to changes
+            // in a service over time.
+            $libApiVersion = (int)(isset($service['apiversion']) ? $service['apiversion'] : false);
+            if ($dbservice->apiversion !== $libApiVersion) {
+                $dbservice->apiversion = $libApiVersion;
+                $update = true;
+            }
             if ($update) {
                 $dbservice->mtime = db_format_timestamp(time());
                 update_record('external_services', $dbservice);