diff --git a/templates/zerver/api/server-settings.md b/templates/zerver/api/server-settings.md new file mode 100644 index 0000000000..69b965d3a6 --- /dev/null +++ b/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 + +
+ +
+ +
+ +``` +curl {{ api_url }}/v1/server_settings \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY +``` + +
+ +
+ +{generate_code_example(python)|/server_settings:get|example} + +
+ +
+ +
+ +## 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)} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index 8ce18de740..dc939ceb9b 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/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) diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index c9e244eb14..bca9c9cc5c 100644 --- a/zerver/lib/api_test_helpers.py +++ b/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 diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 9fed3f2cce..23df1df855 100644 --- a/zerver/openapi/zulip.yaml +++ b/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": "

The Zulip development environment default organization. It's great for testing!

", + "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.