doc/api/reference/prepare.rst

   1 .. _prepared-response-api:
   2
   3 Prepared Response API
   4 =====================
   5
   6 This API is used by other parts of the API. It is not supposed to be initiated
   7 by clients directly.
   8
   9 Some requests might require the server to prepare a response. This process can
  10 take longer than common request timeouts.
  11
  12 In such cases, the server will provide a URL from which the response can be
  13 retrieved.
  14
  15
  16 Resources
  17 ---------
  18
  19 The Prepared Response API defines the following resources ::
  20
  21  /response/<id>
  22
  23
  24 Prepared Responses
  25 ------------------
  26
  27 The server can indicate a prepared response in the following way. ::
  28
  29     303 See Other
  30     Link: /response/<id>
  31
  32 Please note that any URL might be used in the ``Link`` header.
  33
  34 The server is preparing the result at the specified resource. The client should
  35 try to fetch the data from the given URLs. ::
  36
  37     GET /response/<id>
  38     Content-Tpe: application/json
  39
  40
  41 A status code 404 is returned before the data is ready. The client may retry
  42 after the given number of seconds. ::
  43
  44     404 Not Found
  45     Retry-After: 120
  46
  47
  48 When the data is ready, 200 will be returned ::
  49
  50     200 OK
  51     Content-Tpe: application/json
  52
  53     body
  54
  55 When the data is no longer available, a 410 is returned. ::
  56
  57     410 Gone
  58
  59 In this case the client SHOULD retry the previous request.