From cdcaf69fb5ab2d49bce379f54a89d572363ec166 Mon Sep 17 00:00:00 2001
From: Mark Haines <mjark@negativecurvature.net>
Date: Tue, 28 Apr 2015 17:39:03 +0100
Subject: [PATCH] Update 30_server_server_api.rst

---
 specification/30_server_server_api.rst | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst
index d9ce9611..55570507 100644
--- a/specification/30_server_server_api.rst
+++ b/specification/30_server_server_api.rst
@@ -120,9 +120,10 @@ before the ``expired_ts``. The ``expired_ts`` is a millisecond POSIX timestamp
 of when the originating server stopped using that key.
 
 Intermediate perspective servers should cache a response for half of its
-remaining life time to avoid serving a stale response. Servers should avoid
-querying for certificates more frequently than once an hour to avoid flooding
-a server with requests.
+remaining life time to avoid serving a stale response. Originating servers should
+avoid returning responses that expire in less than an hour to avoid repeated
+requests for an about to expire certificate. Requesting servers should limit how
+frequently they query for certificates to avoid flooding a server with requests.
 
 If a server goes offline intermediate perspective servers should continue to
 return the last response they received from that server so that the signatures
@@ -183,6 +184,13 @@ servers. Either way the response is a list of JSON objects containing the
 JSON published by the server under ``_matrix/key/v2/server/`` signed by
 both the originating server and by this server.
 
+The ``minimum_valid_until_ts`` is a millisecond POSIX timestamp indicating 
+when the returned certificate will need to be valid until to be useful to the 
+requesting server. This can be set using the maximum ``origin_server_ts`` of 
+an batch of events that a requesting server is trying to validate. This allows
+an intermediate perspectives server to give a prompt cached response even if
+the originating server is offline.
+
 This API can return keys for servers that are offline be using cached responses
 taken from when the server was online. Keys can be queried from multiple
 servers to mitigate against DNS spoofing.
@@ -191,16 +199,18 @@ Requests:
 
 .. code::
 
-    GET /_matrix/key/v2/query/${server_name}/${key_id} HTTP/1.1
+    GET /_matrix/key/v2/query/${server_name}/${key_id}/${minimum_valid_until_ts} HTTP/1.1
 
     POST /_matrix/key/v2/query HTTP/1.1
     Content-Type: application/json
 
     {
         "server_keys": {
-            "$server_name": [
-                "$key_id"
-            ]
+            "$server_name": {
+                "$key_id": {
+                    "minimum_valid_until_ts": $posix_timestamp
+                }
+            }
         }
     }