template context: Give better names to the URLs for the API.

The "subdomain" label is redundant, to the extent it's even
accurate -- this is really just the URL we want to display,
which may or may not involve a subdomain.  Similarly "external".

The former `external_api_path_subdomain` was never a path -- it's a
host, followed by a path, which together form a scheme-relative URL.
I'm not quite convinced that value is actually the right thing in
2 of the 3 places we use it, but fixing that can start by giving an
accurate name to the thing we have.

docs/integration-docs-guide.md

@@ -99,7 +99,7 @@ Here are a few common macros used to document Zulip's integrations:
 
 * **Contents:** See [source][5]. **Note:** If special configuration is
   required to set up the URL and you can't use this macro, be sure to use the
-  `{{ external_api_uri_subdomain }}` template variable, so that your integration
+  `{{ api_url }}` template variable, so that your integration
   documentation will provide the correct URL for whatever server it is
   deployed on.  If special configuration is required to set the SITE
   variable, you should document that too.

docs/webhook-walkthrough.md

@@ -341,7 +341,7 @@ Next, on your {{ settings_html|safe }}, create a Hello World bot.
 Construct the URL for the Hello World bot using the API key and
 stream name:
 
-`{{ external_api_uri_subdomain }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
+`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
 
 
 To trigger a notification using this webhook, use

static/js/integration_bot_widget.js

@@ -10,9 +10,9 @@ function subscribe_to_stream(bot_email, stream_name) {
 
 // This function puts together the main string for url that will be copied by the user
 // to use for incoming webhook services.
-function put_key_values_in_url(external_api_uri_subdomain, integration_url,
+function put_key_values_in_url(api_url, integration_url,
                                bot_api_key, stream_name) {
-    var integration_bot_url = external_api_uri_subdomain + integration_url +
+    var integration_bot_url = api_url + integration_url +
                               "?api_key=" + bot_api_key +
                               "&stream=" + stream_name;
     return integration_bot_url;
@@ -31,18 +31,18 @@ function update_integration_bot_url(integration_bot_url) {
 }
 
 // This is the function that runs after the bot is created successfully.
-function on_create_bot_success(result, stream_name, external_api_uri_subdomain, integration_url) {
+function on_create_bot_success(result, stream_name, api_url, integration_url) {
     var bot_api_key = result.api_key;
     var bot_email = result.email;
 
     subscribe_to_stream(bot_email, stream_name);
-    var integration_bot_url = put_key_values_in_url(external_api_uri_subdomain, integration_url,
+    var integration_bot_url = put_key_values_in_url(api_url, integration_url,
                                                     bot_api_key, stream_name);
     update_integration_bot_url(integration_bot_url);
 }
 
 function create_bot(full_name, short_name, bot_avatar_file, stream_name,
-                    external_api_uri_subdomain, integration_url, on_success) {
+                    api_url, integration_url, on_success) {
     var formData = new FormData();
     formData.append('csrfmiddlewaretoken', csrf_token);
     formData.append('full_name', full_name);
@@ -56,7 +56,7 @@ function create_bot(full_name, short_name, bot_avatar_file, stream_name,
         contentType: false,
         success: function (resp, statusText, xhr) {
             var result = JSON.parse(xhr.responseText);
-            on_success(result, stream_name, external_api_uri_subdomain, integration_url);
+            on_success(result, stream_name, api_url, integration_url);
         },
         error: function (xhr) {
             // UI yet to be created with this div id
@@ -67,11 +67,11 @@ function create_bot(full_name, short_name, bot_avatar_file, stream_name,
 
 // This is the main function to be called to set the integration bot url.
 exports.set_integration_bot_url = function (
-    external_api_uri_subdomain, integration_url, bot_full_name,
+    api_url, integration_url, bot_full_name,
     bot_short_name, bot_avatar_file, bot_owner, stream_name
 ) {
     create_bot(bot_full_name, bot_short_name, bot_avatar_file,
-               stream_name, external_api_uri_subdomain, integration_url, on_create_bot_success);
+               stream_name, api_url, integration_url, on_create_bot_success);
 };
 
 return exports;

templates/zerver/api.html

@@ -47,7 +47,7 @@ Sample steps to do:
 #}
 
 <h4>Stream message</h4>
-<div class="codehilite"><pre>curl {{ external_api_uri_subdomain }}/v1/messages <span class="se">\</span>
+<div class="codehilite"><pre>curl {{ api_url }}/v1/messages <span class="se">\</span>
     -u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
     -d <span class="s2">"type=stream"</span> <span class="se">\</span>
     -d <span class="s2">"to=Denmark"</span> <span class="se">\</span>
@@ -56,7 +56,7 @@ Sample steps to do:
 </div>
 
 <h4>Private message</h4>
-<div class="codehilite"><pre>curl {{ external_api_uri_subdomain }}/v1/messages <span class="se">\</span>
+<div class="codehilite"><pre>curl {{ api_url }}/v1/messages <span class="se">\</span>
     -u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
     -d <span class="s2">"type=private"</span> <span class="se">\</span>
     -d <span class="s2">"to=hamlet@example.com"</span> <span class="se">\</span>
@@ -74,7 +74,7 @@ Sample steps to do:
 <span class="c"># Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc</span>
 <span class="n">client</span> <span class="o">=</span> <span class="n">zulip</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="p">email</span><span class="o">=</span><span class="s">"othello-bot@example.com"</span><span class="p">,</span>
                       <span class="n">api_key</span><span class="o">=</span><span class="s">"a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5"</span><span class="p">,</span>
-                      <span class="n">site</span><span class="o">=</span><span class="s">"{{ external_api_uri_subdomain }}"</span><span class="p">)</span>
+                      <span class="n">site</span><span class="o">=</span><span class="s">"{{ api_url }}"</span><span class="p">)</span>
 <span class="c"># Send a stream message</span>
 <span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">({</span>
     <span class="s">"type"</span><span class="p">:</span> <span class="s">"stream"</span><span class="p">,</span>
@@ -107,19 +107,19 @@ Sample steps to do:
 <h4>Stream message</h4>
 <div class="codehilite"><pre>zulip-send --stream Denmark --subject Castle \
 --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ external_api_uri_subdomain }}</pre></div>
+--site={{ api_url }}</pre></div>
 
 <h4>Private message</h4>
 <div class="codehilite"><pre>zulip-send hamlet@example.com \
 --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ external_api_uri_subdomain }}</pre></div>
+--site={{ api_url }}</pre></div>
 
 <h4>Passing in the message on the command-line</h4>
 <p>If you'd like, you can also provide the message on the command-line with the <code>-m</code> flag, as follows:</p>
 <div class="codehilite"><pre>zulip-send --stream Denmark --subject Castle \
 -m <span class="s2">"Something is rotten in the state of Denmark."</span> \
 --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
---site={{ external_api_uri_subdomain }}
+--site={{ api_url }}
 </pre></div>
 
       <p>You can omit the <code>user</code>, <code>api-key</code>, and
@@ -137,7 +137,7 @@ Sample steps to do:
 <span class="kr">const</span> <span class="nx">config</span> <span class="o">=</span> <span class="p">{</span>
   <span class="nx">username</span><span class="o">:</span> <span class="s1">'othello-bot@example.com'</span><span class="p">,</span>
   <span class="nx">apiKey</span><span class="o">:</span> <span class="s1">'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5'</span><span class="p">,</span>
-  <span class="nx">realm</span><span class="o">:</span> <span class="s1">'{{ external_api_uri_subdomain }}'</span>
+  <span class="nx">realm</span><span class="o">:</span> <span class="s1">'{{ api_url }}'</span>
 <span class="p">};</span>
 
 <span class="kr">const</span> <span class="nx">client</span> <span class="o">=</span> <span class="nx">zulip</span><span class="p">(</span><span class="nx">config</span><span class="p">);</span>
@@ -192,7 +192,7 @@ Sample steps to do:
 <div class="codehilite"><pre><span class="k">[api]</span>
 <span class="na">key</span><span class="o">=</span><span class="s">BOT_API_KEY</span>
 <span class="na">email</span><span class="o">=</span><span class="s">BOT_EMAIL_ADDRESS</span>
-<span class="na">site</span><span class="o">=</span><span class="s">{{ external_api_uri_subdomain }}</span></pre></div>
+<span class="na">site</span><span class="o">=</span><span class="s">{{ api_url }}</span></pre></div>
 
     <p>Additionally, you can also specify the parameters as environment variables as follows:</p>
 <div class="codehilite"><pre><span></span><span class="nb">export</span> <span class="nv">ZULIP_CONFIG</span><span class="o">=</span>/path/to/zulipconfig

templates/zerver/help/include/git-webhook-url-with-branches.md

@@ -2,4 +2,4 @@ You can also limit the branches you receive notifications for by
 specifying them in a comma-separated list at the end of the URL,
 like so:
 
-`{{ external_api_uri_subdomain }}{{ integration_url }}?api_key=abcdefgh&stream={{ recommended_stream_name }}&branches=master,development`
+`{{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream={{ recommended_stream_name }}&branches=master,development`

templates/zerver/help/include/webhook-url-with-bot-email.md

@@ -1,6 +1,6 @@
 In the URL field, enter:
 
-`{{ external_uri_scheme }}bot_email:bot_api_key@{{ external_api_path_subdomain }}{{ integration_url }}`
+`{{ external_uri_scheme }}bot_email:bot_api_key@{{ api_url_scheme_relative }}{{ integration_url }}`
 
 Replace `bot_email` and `bot_api_key` above with the URL-encoded email
 address and API key of the bot.  To URL-encode the email address, you

templates/zerver/help/include/webhook-url.md

@@ -1 +1 @@
-`{{ external_api_uri_subdomain }}{{ integration_url }}?api_key=abcdefgh&stream={{ recommended_stream_name }}`
+`{{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream={{ recommended_stream_name }}`

templates/zerver/help/include/zulip-config.md

@@ -1,5 +1,5 @@
 ```
 ZULIP_USER = "{{ integration_name }}-bot@example.com"
 ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"
-ZULIP_SITE = "{{ external_api_uri_subdomain }}"
+ZULIP_SITE = "{{ api_url }}"
 ```

templates/zerver/integrations/asana.md

@@ -6,7 +6,7 @@ Next, on your {{ settings_html|safe }}, create a bot for Asana.
 Construct the URL for the Asana bot using the bot API key and
 stream name, like so:
 
-`{{ external_api_uri_subdomain }}/v1/external/zapier?api_key=abcdefgh&stream=asana`
+`{{ api_url }}/v1/external/zapier?api_key=abcdefgh&stream=asana`
 
 Start by setting up a [Zapier](https://zapier.com/) account.
 

templates/zerver/integrations/capistrano.md

@@ -16,7 +16,7 @@ namespace :notify do
     # ~/.zuliprc if you omit --user and --api-key
     run_locally "echo ':beers: I just deployed to #{stage}! :beers:' | zulip-send \
     --user capistrano-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
-    --site={{ external_api_uri_subdomain }} \
+    --site={{ api_url }} \
     --stream commits --subject deployments || true"
   end
 end

templates/zerver/integrations/hubot.md

@@ -15,7 +15,7 @@
    variables by running:
 
 ```
-export HUBOT_ZULIP_SITE="{{ external_api_path_subdomain }}"
+export HUBOT_ZULIP_SITE="{{ api_url_scheme_relative }}"
 export HUBOT_ZULIP_BOT="hubot-bot@example.com"
 export HUBOT_ZULIP_API_KEY="your_key"
 ```

templates/zerver/integrations/jira-plugin.md

@@ -28,7 +28,7 @@ default in the Java installation shipped with JIRA, you will need to
 tell JIRA about the certificate.
 
 1. Navigate to **Administration > System > Configure SSL** and in the
-   **Import SSL Certificates** field, enter `{{ external_api_uri_subdomain }}`.
+   **Import SSL Certificates** field, enter `{{ api_url }}`.
 
 2. After clicking **Save Certificates**, follow the on-screen
    instructions and restart JIRA for it to recognize the proper

templates/zerver/integrations/mercurial.md

@@ -20,7 +20,7 @@ hook if it installs in a different location on this system:
         email = "hg-bot@example.com"
         api_key = "0123456789abcdefg"
         stream = "commits"
-        site = {{ external_api_uri_subdomain }}
+        site = {{ api_url }}
 
 That’s all it takes for the basic setup! On the next `hg push`, you’ll
 get a Zulip update for the changeset.
@@ -44,7 +44,7 @@ notifications:
     api_key = "0123456789abcdefg"
     stream = "commits"
     web_url = "http://hg.example.com:8000/"
-    site = {{ external_api_uri_subdomain }}
+    site = {{ api_url }}
 
 [1]: http://mercurial.selenic.com/wiki/QuickStart#Network_support
 

templates/zerver/integrations/nagios.md

@@ -14,7 +14,7 @@ on your Nagios server:
 [api]
 email = NAGIOS_BOT_EMAIL_ADDRESS
 key = NAGIOS_BOT_API_KEY
-site = {{ external_api_uri_subdomain }}
+site = {{ api_url }}
 ```
 
 Copy `integrations/nagios/zulip_nagios.cfg` to `/etc/nagios3/conf.d`

templates/zerver/integrations/redmine.md

@@ -39,7 +39,7 @@ you want these settings to apply.
 To configure Zulip notifications for a particular Redmine project,
 visit the project's **Settings** page.
 
-In either case, fill out zulip server by `{{ external_api_path_subdomain }}`
+In either case, fill out zulip server by `{{ api_url_scheme_relative }}`
 the bot email address, and API key, and the Zulip stream that should
 receive notifications. Apply your changes.
 

tools/linter_lib/custom_check.py

@@ -95,7 +95,7 @@ def custom_check_file(fn, identifier, rules, color, skip_rules=None, max_length=
         if (max_length is not None and line_length > max_length and
             '# type' not in line and 'test' not in fn and 'example' not in fn and
             not re.match("\[[ A-Za-z0-9_:,&()-]*\]: http.*", line) and
-            not re.match("`\{\{ external_api_uri_subdomain \}\}[^`]+`", line) and
+            not re.match("`\{\{ api_url \}\}[^`]+`", line) and
                 "#ignorelongline" not in line and 'migrations' not in fn):
             print("Line too long (%s) at %s line %s: %s" % (len(line), fn, i+1, line_newline_stripped))
             failed = True

zerver/tests/test_docs.py

@@ -119,8 +119,8 @@ class IntegrationTest(TestCase):
         # type: () -> None
         context = dict()  # type: Dict[str, Any]
         add_api_uri_context(context, HostRequestMock())
-        self.assertEqual(context["external_api_path_subdomain"], "testserver/api")
-        self.assertEqual(context["external_api_uri_subdomain"], "http://testserver/api")
+        self.assertEqual(context["api_url_scheme_relative"], "testserver/api")
+        self.assertEqual(context["api_url"], "http://testserver/api")
         self.assertTrue(context["html_settings_links"])
 
     @override_settings(ROOT_DOMAIN_LANDING_PAGE=True)
@@ -128,8 +128,8 @@ class IntegrationTest(TestCase):
         # type: () -> None
         context = dict()  # type: Dict[str, Any]
         add_api_uri_context(context, HostRequestMock())
-        self.assertEqual(context["external_api_path_subdomain"], "yourZulipDomain.testserver/api")
-        self.assertEqual(context["external_api_uri_subdomain"], "http://yourZulipDomain.testserver/api")
+        self.assertEqual(context["api_url_scheme_relative"], "yourZulipDomain.testserver/api")
+        self.assertEqual(context["api_url"], "http://yourZulipDomain.testserver/api")
         self.assertFalse(context["html_settings_links"])
 
     def test_api_url_view_subdomains_full(self):
@@ -137,8 +137,8 @@ class IntegrationTest(TestCase):
         context = dict()  # type: Dict[str, Any]
         request = HostRequestMock(host="mysubdomain.testserver")
         add_api_uri_context(context, request)
-        self.assertEqual(context["external_api_path_subdomain"], "mysubdomain.testserver/api")
-        self.assertEqual(context["external_api_uri_subdomain"], "http://mysubdomain.testserver/api")
+        self.assertEqual(context["api_url_scheme_relative"], "mysubdomain.testserver/api")
+        self.assertEqual(context["api_url"], "http://mysubdomain.testserver/api")
         self.assertTrue(context["html_settings_links"])
 
     def test_integration_view_html_settings_links(self):

zerver/views/integrations.py

@@ -27,16 +27,15 @@ def add_api_uri_context(context, request):
         display_subdomain = 'yourZulipDomain'
         html_settings_links = False
     if display_subdomain != Realm.SUBDOMAIN_FOR_ROOT_DOMAIN:
-        external_api_path_subdomain = '%s.%s/api' % (display_subdomain,
+        api_url_scheme_relative = '%s.%s/api' % (display_subdomain,
                                                  settings.EXTERNAL_HOST)
     else:
-        external_api_path_subdomain = settings.EXTERNAL_HOST + "/api"
+        api_url_scheme_relative = settings.EXTERNAL_HOST + "/api"
 
-    external_api_uri_subdomain = '%s%s' % (settings.EXTERNAL_URI_SCHEME,
-                                           external_api_path_subdomain)
+    api_url = '%s%s' % (settings.EXTERNAL_URI_SCHEME, api_url_scheme_relative)
 
-    context['external_api_path_subdomain'] = external_api_path_subdomain
-    context['external_api_uri_subdomain'] = external_api_uri_subdomain
+    context['api_url_scheme_relative'] = api_url_scheme_relative
+    context['api_url'] = api_url
     context["html_settings_links"] = html_settings_links
 
 class ApiURLView(TemplateView):
@@ -151,11 +150,11 @@ def api_endpoint_docs(request):
     langs = set()
     for call in calls:
         call["endpoint"] = "%s/v1/%s" % (
-            context["external_api_uri_subdomain"],
+            context["api_url"],
             call["endpoint"])
         call["example_request"]["curl"] = call["example_request"]["curl"].replace(
             "https://api.zulip.com",
-            context["external_api_uri_subdomain"])
+            context["api_url"])
         response = call['example_response']
         if '\n' not in response:
             # For 1-line responses, pretty-print them

zerver/webhooks/deskdotcom/doc.md

@@ -17,7 +17,7 @@ Fill in the form like this:
 
 * **Name**: Zulip
 * **Authentication Method**: Basic Auth
-* **URL**: `{{ external_api_uri_subdomain }}/v1/external/deskdotcom`
+* **URL**: `{{ api_url }}/v1/external/deskdotcom`
 * **User name**: *your bot's user name, e.g.* `desk-bot@yourdomain.com`
 * **Password**: *your bot's API key*
 

zerver/webhooks/freshdesk/doc.md

@@ -31,7 +31,7 @@ parts.
 4. In the **Action** section, add a new action of type **Trigger Webhook**.
    Set the **Request Type** to **POST**. Set the following **Callback URL**,
    replacing the Zulip stream with your desired stream:
-   `{{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk`
+   `{{ api_url }}/v1/external/freshdesk?stream=freshdesk`
 
 5. Check the **Requires Authentication** box, and supply the bot email
    address and API key. The **Action** section should look like this so
@@ -103,7 +103,7 @@ changes, please continue to the next section.
    **Trigger Webhook**. Set the **Request Type** to **POST**. Set the
    following **Callback URL**, replacing the Zulip stream with your
    desired stream:
-   `{{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk`
+   `{{ api_url }}/v1/external/freshdesk?stream=freshdesk`
 
 8. Check the **Requires Authentication** box, and supply the bot e-mail
    address and API key. The Action section should look like this so far:

zerver/webhooks/github/doc.md

@@ -22,7 +22,7 @@ To find the Zulip hook, you have to click on **Configure services**.
 Select **Zulip** from the list of service hooks. Fill in the API key
 and email address for your bot that you created earlier and check
 the **"active"** checkbox. Specify
-`{{ external_api_uri_subdomain }}/v1/external/github` as the
+`{{ api_url }}/v1/external/github` as the
 **Alternative endpoint**. You can optionally supply the Zulip stream
 (the default is `commits`) and restrict Zulip notifications to a
 specified set of branches.

zerver/webhooks/helloworld/doc.md

@@ -8,7 +8,7 @@ Next, on your {{ settings_html|safe }}, create a Hello World bot.
 Construct the URL for the Hello World bot using the API key and
 stream name:
 
-`{{ external_api_uri_subdomain }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
+`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
 
 
 To trigger a notification using this webhook, use

zerver/webhooks/homeassistant/doc.md

@@ -14,7 +14,7 @@ the `homeassistant` stream.
 
 And the URL under `resource` should start with:
 
-`{{ external_api_uri_subdomain }}/v1/external/homeassistant`
+`{{ api_url }}/v1/external/homeassistant`
 
 Finally, you need to configure a trigger for the service by adding
 an automation entry in the HomeAssistant `configuration.yaml` file.

zerver/webhooks/travis/doc.md

@@ -9,7 +9,7 @@ Finally, set up a webhook in your `.travis.yml` file:
 ```
 notifications:
 webhooks:
-- {{ external_api_uri_subdomain }}/v1/external/travis?stream=travis&topic=build-status&api_key=abcdefgh
+- {{ api_url }}/v1/external/travis?stream=travis&topic=build-status&api_key=abcdefgh
 ```
 
 By default, pull request events are ignored since most people

zerver/webhooks/yo/doc.md

@@ -5,7 +5,7 @@ First, on your {{ settings_html|safe }}, create a bot for
 {{ integration_display_name }} bot using the bot API key
 and the email address associated with your Zulip account:
 
-`{{ external_api_uri_subdomain }}{{ integration_url }}?api_key=abcdefgh&email=awesome@zulip.example.com`
+`{{ api_url }}{{ integration_url }}?api_key=abcdefgh&email=awesome@zulip.example.com`
 
 Modify the parameters of the URL above, where `api_key` is the API key
 of your Zulip bot.

zerver/webhooks/zendesk/doc.md

@@ -4,7 +4,7 @@ Next, on your {{ settings_html|safe }}, create a bot.
 
 Construct a webhook URL like the following:
 
-`{{ external_api_uri_subdomain }}/v1/external/zendesk?ticket_title={% raw %}{{ ticket.title }}&ticket_id={{ ticket.id }}{% endraw %}`
+`{{ api_url }}/v1/external/zendesk?ticket_title={% raw %}{{ ticket.title }}&ticket_id={{ ticket.id }}{% endraw %}`
 
 {!append-stream-name.md!}