github.com/olivere/camlistore@v0.0.0-20140121221811-1b7ac2da0199/doc/protocol/blob-stat-protocol.txt (about)

     1  This document describes the "batch stat" API end-point, for checking
     2  the size/existence of multiple blobs when the client and/or server do
     3  not support SPDY or HTTP/2.0.  See blob-upload-protocol.txt for more
     4  background.
     5  
     6  Notably: the HTTP method may be GET or POST.  GET is more correct but
     7  be aware that HTTP servers and proxies start to suck around the 2k and
     8  4k URL lengths.  If you're stat'ing more than ~37 blobs, using POST
     9  would be safest.
    10  
    11  The HTTP request path is $blobRoot/camli/stat.  See
    12  blob-upload-protocol.txt and discovery.txt for background.
    13  
    14  In either case, the request form values: (either in the URL for GET or
    15  application/x-www-form-urlencoded body for POST)
    16  
    17     camliversion    required   Version of camlistore and/or stat protocol;
    18                                reserved for future use.  Must be "1" for now.
    19  
    20     blob<n>         optional/  Must start at 1 and go up, no gaps allowed, not
    21                     repeated   zero-padded, etc.  Value is a blobref, e.g
    22                                "sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8"
    23                                There's no defined limit on how many you include here,
    24                                but servers may return a 400 Bad Request if you ask
    25                                for too many.  All servers should support <= 1000
    26                                though.
    27  
    28     maxwaitsec      optional   The client may send this, an integer max number
    29                                of seconds the client is willing to wait
    30                                for the arrival of blobs.  If the server
    31                                supports long-polling (an optional
    32                                feature), then the server will return
    33                                immediately if all the requested blobs
    34                                or available, or wait up until this
    35                                amount of time for the blobs to become
    36                                available.  The server's reply must
    37                                include "canLongPoll" set to true if the
    38                                server supports this feature.  Even if
    39                                the server supports long polling, the
    40                                server may cap 'maxwaitsec' and wait for
    41                                less time than requested by the client.
    42  
    43  Examples:
    44  
    45  GET /some-blob-root/camli/stat?camliversion=1&blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8 HTTP/1.1
    46  Host: example.com
    47  
    48   -or-
    49  
    50  POST /some-blob-root/camli/stat HTTP/1.1
    51  Content-Type: application/x-www-form-urlencoded
    52  Host: example.com
    53  
    54  camliversion=1&
    55  blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8&
    56  blob2=sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd&
    57  blob3=sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
    58  
    59  --------------------------------------------------
    60  Response:
    61  --------------------------------------------------
    62  
    63  HTTP/1.1 200 OK
    64  Content-Length: ...
    65  Content-Type: text/javascript
    66  
    67  {
    68     "stat": [
    69        {"blobRef": "sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
    70         "size": 12312}
    71     ],
    72     "canLongPoll": true
    73  }
    74  
    75  Response keys:
    76  
    77     stat             required   Array of {"blobRef": BLOBREF, "size": INT_bytes}
    78                                 for blobs that the system already has. Empty
    79                                 list if no blobs are already present.
    80  
    81     canLongPoll      optional   Set to true (type boolean) if the server supports
    82                                 long polling.  If not true, the server ignores
    83                                 the client's "maxwaitsec" parameter.