mirror of
https://github.com/zulip/zulip.git
synced 2025-11-05 06:23:38 +00:00
api docs: Document GET /server_settings.
This commit is contained in:
Yago González
committed by
Tim Abbott
Tim Abbott
parent
e92ec362ca
commit
c36cf95dc8
85
templates/zerver/api/server-settings.md
Normal file
85
templates/zerver/api/server-settings.md
Normal file
@@ -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)}
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user