# HG changeset patch
# User Matthew Wild <mwild1@gmail.com>
# Date 1524987234 -3600
# Node ID e6f91e00b50734cd5b3593187528ba29a032401c
# Parent  902ecd6400bdc71a9e62eb47c9d2bd13586ef878
mod_http_roster_admin: Add missing protocol docs

diff -r 902ecd6400bd -r e6f91e00b507 mod_http_roster_admin/README.markdown
--- a/mod_http_roster_admin/README.markdown	Tue Apr 17 14:00:40 2018 +0200
+++ b/mod_http_roster_admin/README.markdown	Sun Apr 29 08:33:54 2018 +0100
@@ -44,7 +44,37 @@
 set to “http://app.example.org/contacts/%s”, then Prosody will make a
 GET request to http://app.example.org/contacts/john
 
-## Notifying Prosody of roster changes
+## Protocol
+
+### Fetching rosters (Prosody to web app)
+
+Prosody considers the web application to always hold the most accurate and up-to-date
+version of the user's roster. When a user first connects, Prosody fetches the roster
+from the web application and caches it internally.
+
+Prosody will make a GET request to the URL specified in Prosody's configuration parameter
+'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username.
+
+For example, when the user 'john' connects to Prosody, and http_roster_url is set
+to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john".
+
+The web app must return a JSON object, where each key is the JID of a contact, and the corresponding
+value is data about that contact.
+
+If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response
+with the following contents:
+
+    {
+        "marie@example.com": {
+            "name": "Marie"
+        },
+    
+        "michael@example.com": {
+            "name": "Michael"
+        }
+    }
+
+### Notifying Prosody of roster changes
 
 The external service needs to notify Prosody whenever a user's roster
 changes. To do this, it must make an HTTP POST request to either: