From 929724e5e71d7497b7636f6d99b7fc03d1e7a131 Mon Sep 17 00:00:00 2001
From: Eeshan Garg <jerryguitarist@gmail.com>
Date: Tue, 6 Feb 2018 16:34:07 -0330
Subject: [PATCH] api docs: Add page for common error payloads.

We now have a separate page for common error payloads, for example,
the payload for when the client's API key is invalid. All error
payloads that are presented on this page will be tested similarly
to our other non-error sample fixtures.
---
 templates/zerver/api/add-subscriptions.md             |  2 --
 templates/zerver/api/common-error-payloads.md         |  7 +++++++
 templates/zerver/api/create-user.md                   |  2 --
 templates/zerver/api/delete-queue.md                  |  2 --
 templates/zerver/api/fixtures.json                    |  4 ++++
 templates/zerver/api/get-all-streams.md               |  2 --
 templates/zerver/api/get-all-users.md                 |  2 --
 templates/zerver/api/get-events-from-queue.md         |  2 --
 templates/zerver/api/get-profile.md                   |  2 --
 templates/zerver/api/get-stream-id.md                 |  2 --
 templates/zerver/api/get-subscribed-streams.md        |  2 --
 templates/zerver/api/private-message.md               |  2 --
 templates/zerver/api/register-queue.md                |  2 --
 templates/zerver/api/remove-subscriptions.md          |  2 --
 templates/zerver/api/render-message.md                |  2 --
 templates/zerver/api/sidebar.md                       |  4 ++++
 templates/zerver/api/stream-message.md                |  2 --
 templates/zerver/api/update-message.md                |  2 --
 .../help/include/invalid-api-key-json-response.md     |  8 --------
 tools/test-api                                        | 11 ++++++++++-
 zerver/lib/api_test_helpers.py                        |  9 +++++++--
 21 files changed, 32 insertions(+), 41 deletions(-)
 create mode 100644 templates/zerver/api/common-error-payloads.md
 delete mode 100644 templates/zerver/help/include/invalid-api-key-json-response.md

diff --git a/templates/zerver/api/add-subscriptions.md b/templates/zerver/api/add-subscriptions.md
index 085c675f46..f98fd8da5e 100644
--- a/templates/zerver/api/add-subscriptions.md
+++ b/templates/zerver/api/add-subscriptions.md
@@ -149,5 +149,3 @@ a private stream and `authorization_errors_fatal` is `False`:
     }
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/common-error-payloads.md b/templates/zerver/api/common-error-payloads.md
new file mode 100644
index 0000000000..1ec8194eb9
--- /dev/null
+++ b/templates/zerver/api/common-error-payloads.md
@@ -0,0 +1,7 @@
+# Sample payloads for common errors
+
+## Invalid API key
+
+A typical failed JSON response for when the API key is invalid:
+
+{generate_code_example|invalid-api-key|fixture}
diff --git a/templates/zerver/api/create-user.md b/templates/zerver/api/create-user.md
index 2dfcb3cb76..9955411ae7 100644
--- a/templates/zerver/api/create-user.md
+++ b/templates/zerver/api/create-user.md
@@ -84,5 +84,3 @@ email address already exists in the realm:
     'result':'error'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/delete-queue.md b/templates/zerver/api/delete-queue.md
index 4585b0903c..54eab7ce1f 100644
--- a/templates/zerver/api/delete-queue.md
+++ b/templates/zerver/api/delete-queue.md
@@ -98,5 +98,3 @@ associated queue has already been deleted:
     'msg':'Bad event queue id: 1515096410:2'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/fixtures.json b/templates/zerver/api/fixtures.json
index df89e10e45..e704c9bc6e 100644
--- a/templates/zerver/api/fixtures.json
+++ b/templates/zerver/api/fixtures.json
@@ -188,5 +188,9 @@
             "new stream"
         ],
         "result":"success",
+    },
+    "invalid-api-key": {
+        "msg":"Invalid API key",
+        "result":"error"
     }
 }
diff --git a/templates/zerver/api/get-all-streams.md b/templates/zerver/api/get-all-streams.md
index 58f3891ab9..dc3b7f3472 100644
--- a/templates/zerver/api/get-all-streams.md
+++ b/templates/zerver/api/get-all-streams.md
@@ -89,5 +89,3 @@ to use the `include_all_active` parameter:
     'msg':'User not authorized for this query'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/get-all-users.md b/templates/zerver/api/get-all-users.md
index c22935a0ea..69aeb5281d 100644
--- a/templates/zerver/api/get-all-users.md
+++ b/templates/zerver/api/get-all-users.md
@@ -154,5 +154,3 @@ A typical successful JSON response may look like:
     'result':'success'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/get-events-from-queue.md b/templates/zerver/api/get-events-from-queue.md
index a9a4af57dc..be999ee330 100644
--- a/templates/zerver/api/get-events-from-queue.md
+++ b/templates/zerver/api/get-events-from-queue.md
@@ -184,5 +184,3 @@ A typical successful JSON response may look like:
     ]
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/get-profile.md b/templates/zerver/api/get-profile.md
index 9facb3af31..21bc3ab931 100644
--- a/templates/zerver/api/get-profile.md
+++ b/templates/zerver/api/get-profile.md
@@ -70,5 +70,3 @@ The rest of the return values are quite self-descriptive.
 A typical successful JSON response may look like:
 
 {generate_code_example|get-profile|fixture}
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/get-stream-id.md b/templates/zerver/api/get-stream-id.md
index ab6d4f6aa2..b78a240804 100644
--- a/templates/zerver/api/get-stream-id.md
+++ b/templates/zerver/api/get-stream-id.md
@@ -89,5 +89,3 @@ not provided:
     "code":"REQUEST_VARIABLE_MISSING"
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/get-subscribed-streams.md b/templates/zerver/api/get-subscribed-streams.md
index e598d15bc8..5635de9639 100644
--- a/templates/zerver/api/get-subscribed-streams.md
+++ b/templates/zerver/api/get-subscribed-streams.md
@@ -87,5 +87,3 @@ This request takes no arguments.
 A typical successful JSON response may look like:
 
 {generate_code_example|get-subscribed-streams|fixture}
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/private-message.md b/templates/zerver/api/private-message.md
index 6deebc22cc..08a5d3fe92 100644
--- a/templates/zerver/api/private-message.md
+++ b/templates/zerver/api/private-message.md
@@ -99,5 +99,3 @@ address is invalid:
     'result':'error'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/register-queue.md b/templates/zerver/api/register-queue.md
index 07576eb08c..205a93d62f 100644
--- a/templates/zerver/api/register-queue.md
+++ b/templates/zerver/api/register-queue.md
@@ -100,5 +100,3 @@ A typical successful JSON response may look like:
     'msg':''
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/remove-subscriptions.md b/templates/zerver/api/remove-subscriptions.md
index 016459b2ce..66860b712a 100644
--- a/templates/zerver/api/remove-subscriptions.md
+++ b/templates/zerver/api/remove-subscriptions.md
@@ -99,5 +99,3 @@ that doesn't exist:
     "result":"error"
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/render-message.md b/templates/zerver/api/render-message.md
index 520fb5a43c..3e78152b4d 100644
--- a/templates/zerver/api/render-message.md
+++ b/templates/zerver/api/render-message.md
@@ -81,5 +81,3 @@ is not supplied:
     'var_name':'content'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md
index 1aff1f0d4e..9a922e7e5d 100644
--- a/templates/zerver/api/sidebar.md
+++ b/templates/zerver/api/sidebar.md
@@ -44,3 +44,7 @@
 * [Register a queue](/api/register-queue)
 * [Get events from queue](/api/get-events-from-queue)
 * [Delete a queue](/api/delete-queue)
+
+#### Common Errors
+
+* [Example payloads](/api/common-error-payloads)
diff --git a/templates/zerver/api/stream-message.md b/templates/zerver/api/stream-message.md
index 9cc4d37892..19a4a64b61 100644
--- a/templates/zerver/api/stream-message.md
+++ b/templates/zerver/api/stream-message.md
@@ -111,5 +111,3 @@ A typical failed JSON response for when the target stream does not exist:
     'result':'error'
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/update-message.md b/templates/zerver/api/update-message.md
index 88ff011ed3..f5ea225ecf 100644
--- a/templates/zerver/api/update-message.md
+++ b/templates/zerver/api/update-message.md
@@ -87,5 +87,3 @@ edit a particular message:
     'msg':"You don't have permission to edit this message"
 }
 ```
-
-{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/help/include/invalid-api-key-json-response.md b/templates/zerver/help/include/invalid-api-key-json-response.md
deleted file mode 100644
index 94e45328c7..0000000000
--- a/templates/zerver/help/include/invalid-api-key-json-response.md
+++ /dev/null
@@ -1,8 +0,0 @@
-A typical failed JSON response for when the API key is invalid:
-
-```
-{
-    'msg':'Invalid API key',
-    'result':'error'
-}
-```
diff --git a/tools/test-api b/tools/test-api
index 68a4f1ee99..4d9408f495 100755
--- a/tools/test-api
+++ b/tools/test-api
@@ -14,7 +14,7 @@ os.chdir(ZULIP_PATH)
 from zulip import Client
 
 from tools.lib.test_server import test_server_running
-from zerver.lib.api_test_helpers import test_the_api
+from zerver.lib.api_test_helpers import test_the_api, test_invalid_api_key
 
 os.environ['DJANGO_SETTINGS_MODULE'] = 'zproject.test_settings'
 django.setup()
@@ -35,4 +35,13 @@ with test_server_running(external_host='zulipdev.com:9981'):
     print("Running API tests...")
     test_the_api(client)
 
+    # Test error payloads
+    client = Client(
+        email=email,
+        api_key='abcedrsdfd',
+        site=site
+    )
+    test_invalid_api_key(client)
+
+
 print("API tests passed!")
diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py
index b4f34357b7..19a8ac8d2b 100644
--- a/zerver/lib/api_test_helpers.py
+++ b/zerver/lib/api_test_helpers.py
@@ -279,6 +279,13 @@ def update_message(client, message_id):
     assert result['result'] == 'success'
     assert result['raw_content'] == request['content']
 
+def test_invalid_api_key(client_with_invalid_key):
+    # type: (Client) -> None
+    result = client_with_invalid_key.list_subscriptions()
+    fixture = FIXTURES['invalid-api-key']
+    test_against_fixture(result, fixture)
+
+
 TEST_FUNCTIONS = {
     'render-message': render_message,
     'stream-message': stream_message,
@@ -343,5 +350,3 @@ def test_the_api(client):
     test_users(client)
     test_streams(client)
     test_messages(client)
-
-    # print(dir(client))