api docs: Document GET /server_settings.

templates/zerver/api/server-settings.md

@@ -0,0 +1,85 @@
+# Get global settings
+
+Fetch global settings for a Zulip server.
+
+`GET {{ api_url }}/v1/server_settings`
+
+**Note:** this endpoint does not require any authentication at all, and you can use it to check:
+
+* If this is a Zulip server, and if so, what version of Zulip it's running.
+* What a Zulip client (e.g. a mobile app or
+  [zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
+  know in order to display a login prompt for the server (e.g. what
+  authentication methods are available).
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/server_settings \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/server_settings:get|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/server_settings:get}
+
+## Response
+
+#### Return values
+
+* `authentication_methods`: object in which each key-value pair in the object
+  indicates whether the authentication method is enabled on this server.
+* `zulip_version`: the version of Zulip running in the server.
+* `push_notifications_enabled`: whether mobile/push notifications are enabled.
+* `email_auth_enabled`: setting for allowing users authenticate with an
+  email-password combination.
+* `require_email_format_usernames`: whether usernames should have an
+  email address format. This is important for clients to know whether
+  the validate email address format in a login prompt; this value will
+  be false if the server has
+  [LDAP authentication][ldap-auth]
+  enabled with a username and password combination.
+* `realm_uri`: the organization's canonical URI.
+* `realm_name`: the organization's name (for display purposes).
+* `realm_icon`: the URI of the organization's icon (usually a logo).
+* `realm_description`: HTML description of the organization, as configured by
+  the [organization profile](/help/create-your-organization-profile).
+
+[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#plug-and-play-sso-google-github-ldap
+
+Please note that not all of these attributes are guaranteed to appear in a
+response, for two reasons:
+
+* This endpoint has evolved over time, so responses from older Zulip servers
+  might be missing some keys (in which case a client should assume the
+  appropriate default).
+* If a `/server_settings` request is made to the root domain of a
+  multi-subdomain server, like the root domain of zulipchat.com, the settings
+  that are realm-specific are not known and thus not provided.
+
+#### Example response
+
+A typical successful JSON response for a single-organization server may look like:
+
+{generate_code_example|/server_settings:get|fixture(200)}

templates/zerver/help/include/rest-endpoints.md

@@ -28,6 +28,10 @@
 
 * [Create organization filters](/api/create-org-filters)
 
+#### Server & organizations
+
+* [Get server settings](/api/server-settings)
+
 #### Real-time events
 * [Real time events API](/api/real-time-events)
 * [Register an event queue](/api/register-queue)

zerver/lib/api_test_helpers.py

@@ -474,6 +474,16 @@ def deregister_queue(client, queue_id):
     result = client.deregister(queue_id)
     validate_against_openapi_schema(result, '/events', 'delete', '400')
 
+def get_server_settings(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Fetch the settings for this server
+    result = client.get_server_settings()
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/server_settings', 'get', '200')
+
 def upload_file(client):
     # type: (Client) -> None
     fp = StringIO("zulip")
@@ -562,6 +572,7 @@ TEST_FUNCTIONS = {
     '/realm/filters:post': add_realm_filter,
     '/register:post': register_queue,
     '/events:delete': deregister_queue,
+    '/server_settings:get': get_server_settings,
     '/user_uploads:post': upload_file,
     '/users/me/{stream_id}/topics:get': get_stream_topics,
     '/typing:post': set_typing_status,
@@ -666,6 +677,7 @@ def test_server_organizations(client):
     # type: (Client) -> None
 
     add_realm_filter(client)
+    get_server_settings(client)
 
 def test_errors(client):
     # type: (Client) -> None

zerver/openapi/zulip.yaml

@@ -1013,6 +1013,79 @@ paths:
                         },
                         "result": "success"
                     }
+  /server_settings:
+    get:
+      description: Fetch global settings for the Zulip server.
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    authentication_methods:
+                      type: object
+                      description: Each key-value pair in the object indicates
+                        whether the authentication method is enabled on this
+                        server.
+                    zulip_version:
+                      type: string
+                      description: The version of Zulip running in the server.
+                    push_notifications_enabled:
+                      type: boolean
+                      description: Whether mobile/push notifications are
+                        enabled.
+                    email_auth_enabled:
+                      type: boolean
+                      description: Setting for allowing users authenticate with
+                        an email-password combination.
+                    require_email_format_usernames:
+                      type: boolean
+                      description: Whether usernames should have an email
+                        address format. This is important if your server has
+                        [LDAP authentication](https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#plug-and-play-sso-google-github-ldap)
+                        enabled with a username and password combination.
+                    realm_uri:
+                      type: string
+                      description: The organization's URI.
+                    realm_name:
+                      type: string
+                      description: The realm's name.
+                    realm_icon:
+                      type: string
+                      description: The URI of the organization's icon (usually
+                        a logo).
+                    realm_description:
+                      type: string
+                      description: HTML description of the organization, as
+                        configured by the
+                        [organization profile](/help/create-your-organization-profile).
+                - example:
+                    {
+                        "realm_uri": "http://localhost:9991",
+                        "push_notifications_enabled": false,
+                        "msg": "",
+                        "realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
+                        "realm_description": "<p>The Zulip development environment default organization.  It's great for testing!</p>",
+                        "email_auth_enabled": true,
+                        "zulip_version": "1.9.0-rc1+git",
+                        "realm_name": "Zulip Dev",
+                        "authentication_methods": {
+                            "github": true,
+                            "ldap": false,
+                            "password": true,
+                            "remoteuser": false,
+                            "email": true,
+                            "google": true,
+                            "dev": true
+                        },
+                        "result": "success",
+                        "require_email_format_usernames": true
+                    }
   /streams:
     get:
       description: Get all streams that the user has access to.