Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

api-docs: Note API feature endpoints without frontend implementation.

Aman Agrawal83cdbfd28c14
diff --git a/api_docs/include/api-pending-web.md b/api_docs/include/api-pending-web.md
new file mode 100644
index 00000000000..96f5b72c0f9
--- /dev/null
+++ b/api_docs/include/api-pending-web.md
@@ -0,0 +1,6 @@
+!!! warn ""
+
+ **Note**: The Zulip web application implementation of this feature is
+ pending. For information about the current state of this API and the
+ feature's development, reach out in [our development
+ community](https://chat.zulip.org).
diff --git a/docs/processes/integration-review.md b/docs/processes/integration-review.md
index b534c992088..7f2cebef8e5 100644
--- a/docs/processes/integration-review.md
+++ b/docs/processes/integration-review.md
@@ -88,6 +88,14 @@ you should hand off to a different reviewer.)
but needlessly isn't, or multi-minute transactions.
- Audit logs and information destruction risks.
+### API documentation
+
+- Occasionally, we will want to merge the API and backend changes for
+ a new feature without also implementing that API/feature in the web
+ app. In this case, any new API endpoints should be labeled with the
+ `x-pending-web-implementation` tag and you'll want to open an issue
+ for the web app implementation of the feature so that it's tracked.
+
### Web app
- Cross-site scripting bugs. Pay special attention to `{{{` in
@@ -100,6 +108,8 @@ you should hand off to a different reviewer.)
workflows (not just settings).
- Error handling that could make a future error/mistake worse. E.g.,
anything touching the logic that reloads the web app.
+- API documentation reflects that the feature is implemented in the
+ web app; see API changes point above.
## Checklist
diff --git a/zerver/openapi/markdown_extension.py b/zerver/openapi/markdown_extension.py
index ef5653ac33f..755b15d0841 100644
--- a/zerver/openapi/markdown_extension.py
+++ b/zerver/openapi/markdown_extension.py
@@ -28,6 +28,7 @@ from zerver.openapi.openapi import (
check_additional_imports,
check_requires_administrator,
check_requires_owner,
+ check_web_app_pending_implementation,
generate_openapi_fixture,
get_curl_include_exclude,
get_openapi_description,
@@ -527,6 +528,11 @@ class APIHeaderPreprocessor(BasePreprocessor):
description_dict = get_openapi_description(path, method)
return [
*("# " + line for line in raw_title.splitlines()),
+ *(
+ ["{!api-pending-web.md!}"]
+ if check_web_app_pending_implementation(path, method)
+ else []
+ ),
*(["{!api-admin-only.md!}"] if check_requires_administrator(path, method) else []),
*(["{!api-owner-only.md!}"] if check_requires_owner(path, method) else []),
"",
diff --git a/zerver/openapi/openapi.py b/zerver/openapi/openapi.py
index f2234d908ea..96ddddb288e 100644
--- a/zerver/openapi/openapi.py
+++ b/zerver/openapi/openapi.py
@@ -232,6 +232,13 @@ def get_curl_include_exclude(endpoint: str, method: str) -> list[dict[str, Any]]
]
+def check_web_app_pending_implementation(endpoint: str, method: str) -> bool:
+ """Fetch if the endpoint has note about web application implementation."""
+ return openapi_spec.openapi()["paths"][endpoint][method.lower()].get(
+ "x-pending-web-implementation", False
+ )
+
+
def check_requires_administrator(endpoint: str, method: str) -> bool:
"""Fetch if the endpoint requires admin config."""
return openapi_spec.openapi()["paths"][endpoint][method.lower()].get(
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 88443ccb7ff..4e66dcf11e9 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -7368,6 +7368,7 @@ paths:
operationId: get-drafts
tags: ["drafts"]
summary: Get drafts
+ x-pending-web-implementation: true
description: |
Fetch all drafts for the current user.
responses:
@@ -7433,6 +7434,7 @@ paths:
operationId: create-drafts
tags: ["drafts"]
summary: Create drafts
+ x-pending-web-implementation: true
description: |
Create one or more drafts on the server. These drafts will be automatically
synchronized to other clients via `drafts` events.
@@ -7504,6 +7506,7 @@ paths:
operationId: edit-draft
tags: ["drafts"]
summary: Edit a draft
+ x-pending-web-implementation: true
description: |
Edit a draft on the server. The edit will be automatically
synchronized to other clients via `drafts` events.
@@ -7564,6 +7567,7 @@ paths:
operationId: delete-draft
tags: ["drafts"]
summary: Delete a draft
+ x-pending-web-implementation: true
description: |
Delete a single draft from the server. The deletion will be automatically
synchronized to other clients via a `drafts` event.
@@ -7600,6 +7604,7 @@ paths:
operationId: get-navigation-views
tags: ["navigation_views"]
summary: Get all navigation views
+ x-pending-web-implementation: true
description: |
Fetch all configured custom navigation views for the current user.
@@ -7639,6 +7644,7 @@ paths:
operationId: add-navigation-view
tags: ["navigation_views"]
summary: Add a navigation view
+ x-pending-web-implementation: true
description: |
Adds a new custom left sidebar navigation view configuration
for the current user.
@@ -7684,6 +7690,7 @@ paths:
operationId: edit-navigation-view
tags: ["navigation_views"]
summary: Update the navigation view
+ x-pending-web-implementation: true
description: |
Update the details of an existing configured navigation view,
such as its name or whether it's pinned.
@@ -7772,6 +7779,7 @@ paths:
operationId: remove-navigation-view
tags: ["navigation_views"]
summary: Remove a navigation view
+ x-pending-web-implementation: true
description: |
Remove a navigation view.