Bug 1920627: Give API key examples in API docs (#202)

diff --git a/docs/en/rst/api/core/v1/general.rst b/docs/en/rst/api/core/v1/general.rst
index 06ef5b2fbc005f142ab339cd87757db2c84dbbd0..7118c4f585e5b2e5107c6192484bfe64f23c00ba 100644 (file)
--- a/docs/en/rst/api/core/v1/general.rst
+++ b/docs/en/rst/api/core/v1/general.rst
@@ -113,6 +113,27 @@ any call, and you will be logged in as that user if the key is correct and has
 not been revoked. You can set up an API key by using the 'API Key' tab in the
 Preferences pages.
 
+Examples:
+
+If using a GET request, make it a query param:
+
+   :samp:`https://mysite/rest/bug/1?api_key={MY_API_KEY}`
+
+If using a POST or PUT request, put it in your JSON payload:
+
+.. code-block:: js
+
+   {
+     "api_key": "MY_API_KEY",
+     "status": "RESOLVED",
+     "resolution": "FIXED"
+   }
+
+Note that it's generally not a good idea to put API keys in the query params,
+as that allows it to be recorded in server logs. API calls that would normally
+be sent as a GET request can also be sent as a POST request with the api_key
+being the only content in your JSON payload.
+
 **Login and Password**
 
 You can specify ``Bugzilla_login`` and ``Bugzilla_password`` or simply