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

@@ -149,5 +149,3 @@ a private stream and `authorization_errors_fatal` is `False`:
     }
 }
 ```
-
-{!invalid-api-key-json-response.md!}

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}

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!}

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!}

templates/zerver/api/fixtures.json

@@ -188,5 +188,9 @@
             "new stream"
         ],
         "result":"success",
+    },
+    "invalid-api-key": {
+        "msg":"Invalid API key",
+        "result":"error"
     }
 }

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!}

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!}

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!}

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!}

templates/zerver/api/get-stream-id.md

@@ -89,5 +89,3 @@ not provided:
     "code":"REQUEST_VARIABLE_MISSING"
 }
 ```
-
-{!invalid-api-key-json-response.md!}

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!}

templates/zerver/api/private-message.md

@@ -99,5 +99,3 @@ address is invalid:
     'result':'error'
 }
 ```
-
-{!invalid-api-key-json-response.md!}

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!}

templates/zerver/api/remove-subscriptions.md

@@ -99,5 +99,3 @@ that doesn't exist:
     "result":"error"
 }
 ```
-
-{!invalid-api-key-json-response.md!}

templates/zerver/api/render-message.md

@@ -81,5 +81,3 @@ is not supplied:
     'var_name':'content'
 }
 ```
-
-{!invalid-api-key-json-response.md!}

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)

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!}

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!}

templates/zerver/help/include/invalid-api-key-json-response.md

@@ -1,8 +0,0 @@
-A typical failed JSON response for when the API key is invalid:
-
-```
-{
-    'msg':'Invalid API key',
-    'result':'error'
-}
-```

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!")

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))