From 14caf656788903a553c4a374b3f9a934a4014033 Mon Sep 17 00:00:00 2001
From: root
Date: Wed, 29 Sep 2010 10:36:17 +0200
Subject: Add doctest for connecting using invalid credentials and some
 documentation regarding the basic auth for the REST server.

---
 src/mailman/rest/docs/basic.txt | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

(limited to 'src/mailman/rest/docs')

diff --git a/src/mailman/rest/docs/basic.txt b/src/mailman/rest/docs/basic.txt
index e5dab9ea8..179185a95 100644
--- a/src/mailman/rest/docs/basic.txt
+++ b/src/mailman/rest/docs/basic.txt
@@ -2,12 +2,20 @@
 REST server
 ===========
 
-Mailman exposes a REST_ HTTP server for administrative control.
+Mailman exposes a REST HTTP server for administrative control.
 
 The server listens for connections on a configurable host name and port.
+
+It is always protected by HTTP basic authentication using a single global
+username and password. The credentials are set in the webservice section
+of the config using the admin_user and admin_pass properties.
+
 Because the REST server has full administrative access, it should always be
-run only on localhost, unless you really know what you're doing.  The Mailman
-major and minor version numbers are in the URL.
+run only on localhost, unless you really know what you're doing. In addition
+you should set the username and password to secure values and distribute
+them to any REST clients with reasonable precautions.
+
+The Mailman major and minor version numbers are in the URL.
 
 System information can be retrieved from the server.  By default JSON is
 returned.
@@ -30,5 +38,16 @@ When you try to access a link that doesn't exist, you get the appropriate HTTP
     ...
     HTTPError: HTTP Error 404: 404 Not Found
 
+Invalid credentials
+===================
+
+When you try to access the REST server using invalid credentials you will get
+an appropriate HTTP 401 Unauthorized error.
+
+    >>> dump_json('http://localhost:8001/3.0/system', None, None, 'baduser', 'badpass')
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 401: 401 Unauthorized
+    ...
 
 .. _REST: http://en.wikipedia.org/wiki/REST
-- 
cgit v1.3