Merge branch 'multiple-base-urls'

This is a slightly updated version of pull request #419.
Should fix the #416 issue.

Author: wrygiel

okapi/core.php

@@ -1219,6 +1219,81 @@ public static function get_oc_schema_code()
         }
     }
 
+    /**
+     * Return the recommended okapi_base_url.
+     *
+     * This is the URL which we want all *new* client applications to use.
+     * OKAPI will suggest URLs with this prefix in various context, e.g. in all
+     * the dynamically generated docs.
+     *
+     * Also see `get_allowed_base_urls` method.
+     */
+    public static function get_recommended_base_url()
+    {
+        return Settings::get('SITE_URL')."okapi/";
+    }
+
+    /**
+     * Return a list of okapi_base_urls allowed to be used when calling OKAPI
+     * methods in this installation.
+     *
+     * Since issue #416, the "recommended" okapi_base_url is *not* the only one
+     * allowed (actually, there were more allowed before issue #416, but they
+     * weren't allowed "officially").
+     */
+    public static function get_allowed_base_urls()
+    {
+        /* Currently, there are no config settings which would let us allow
+         * to determine the proper values for this list. So, we need to have it
+         * hardcoded. (Perhaps we should move this to etc/installations.xml?
+         * But this wouldn't be efficient...) */
+
+        switch (self::get_oc_schema_code()) {
+            case 'OCPL':
+                $urls = array(
+                    "http://opencaching.pl/okapi/",
+                    "http://www.opencaching.pl/okapi/",
+                );
+                break;
+            case 'OCDE':
+                $urls = array(
+                    "http://www.opencaching.de/okapi/",
+                    "https://www.opencaching.de/okapi/",
+                );
+                break;
+            case 'OCNL':
+                $urls = array(
+                    "http://www.opencaching.nl/okapi/",
+                );
+                break;
+            case 'OCRO':
+                $urls = array(
+                    "http://www.opencaching.ro/okapi/",
+                );
+                break;
+            case 'OCORGUK':
+                $urls = array(
+                    "http://www.opencaching.org.uk/okapi/",
+                );
+                break;
+            case 'OCUS':
+                $urls = array(
+                    "http://www.opencaching.us/okapi/",
+                    "http://opencaching.us/okapi/",
+                );
+                break;
+            default:
+                /* Unknown site. No extra allowed URLs. */
+                $urls = array();
+        }
+
+        if (!in_array(self::get_recommended_base_url(), $urls)) {
+            $urls[] = self::get_recommended_base_url();
+        }
+
+        return $urls;
+    }
+
     /**
      * Pick text from $langdict based on language preference $langpref.
      *
@@ -2407,11 +2482,33 @@ public function __construct($options)
     private function init_request()
     {
         $this->request = OAuthRequest::from_request();
-        if (!in_array($this->request->get_normalized_http_method(),
-            array('GET', 'POST')))
-        {
+
+        /* Verify if the request was issued with proper HTTP method. */
+
+        if (!in_array(
+            $this->request->get_normalized_http_method(),
+            array('GET', 'POST')
+        )) {
             throw new BadRequest("Use GET and POST methods only.");
         }
+
+        /* Verify if the request was issued with proper okapi_base_url. */
+
+        $url = $this->request->get_normalized_http_url();
+        $allowed = false;
+        foreach (Okapi::get_allowed_base_urls() as $allowed_prefix) {
+            if (strpos($url, $allowed_prefix) === 0) {
+                $allowed = true;
+                break;
+            }
+        }
+        if (!$allowed) {
+            throw new BadRequest(
+                "Unrecognized base URL prefix! See `okapi_base_urls` field ".
+                "in the `services/apisrv/installation` method. (Recommended ".
+                "base URL to use is '".Okapi::get_recommended_base_url()."'.)"
+            );
+        }
     }
 
     /**

okapi/services/apisrv/installation.php

@@ -20,7 +20,8 @@ public static function call(OkapiRequest $request)
     {
         $result = array();
         $result['site_url'] = Settings::get('SITE_URL');
-        $result['okapi_base_url'] = $result['site_url']."okapi/";
+        $result['okapi_base_url'] = Okapi::get_recommended_base_url();
+        $result['okapi_base_urls'] = Okapi::get_allowed_base_urls();
         $result['site_name'] = Okapi::get_normalized_site_name();
         $result['okapi_version_number'] = Okapi::$version_number;
         $result['okapi_revision'] = Okapi::$version_number; /* Important for backward-compatibility! */

okapi/services/apisrv/installation.xml

@@ -15,10 +15,18 @@
                 level domain of a country).
             </li>
             <li>
-                <b>okapi_base_url</b> - URL of the OKAPI installation (usually this is
-                <b>site_url</b> with "okapi/" appended, but you should not assume
-                that); this value is to be used as a prefix when constructing service
-                method URLs,
+                <b>okapi_base_url</b> - the <i>recommended</i> base URL to be used when
+                accessing this OKAPI installation (it should be used as a prefix when
+                constructing method URLs),
+            </li>
+            <li>
+                <p><b>okapi_base_urls</b> - a list of <i>all</i> base URLs allowed to be used
+                when calling OKAPI methods in this installation.</p>
+                
+                <p>In theory, once a new base URL appears on this list, it should never
+                disappear (it should be allowed to use it forever). However, for various
+                reasons, we cannot guarantee it will indeed be so. Clients SHOULD use the
+                recommended base URL provided in the <b>okapi_base_url</b> field.</p>
             </li>
             <li>
                 <b>site_name</b> - international name of the Opencaching site,

okapi/settings.php

@@ -130,9 +130,12 @@ final class Settings
         'DB_CHARSET' => 'utf8',
 
         /**
-         * URL of this site (with slash, and without "/okapi"). If this is a
-         * development installation, it should point to the local URL (e.g.
-         * "http://localhost/".
+         * Canonical URL of this Opencaching site (with a trailing slash). If
+         * you prefer your site to be accessed via HTTPS, then this should be
+         * a "https://" URL.
+         *
+         * If this is a development installation, it should point to the local
+         * URL (e.g. "http://localhost/").
          */
         'SITE_URL' => null,