From b0a8e554df45abe694fd3be04aadb09ee6d3eaf0 Mon Sep 17 00:00:00 2001
From: Steve Streeting <steve@stevestreeting.com>
Date: Tue, 3 May 2016 15:36:47 +0100
Subject: [PATCH] Discuss API tweaks to allow alternate upload/download
 protocols

---
 docs/api/http-v1-batch.md | 62 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/api/http-v1-batch.md b/docs/api/http-v1-batch.md
index a69f68de..a1c9f4f6 100644
--- a/docs/api/http-v1-batch.md
+++ b/docs/api/http-v1-batch.md
@@ -285,3 +285,65 @@ track usage.
 
 Some server errors may trigger the client to retry requests, such as 500, 502,
 503, and 504.
+
+## Extended upload & download protocols
+
+By default it is assumed that all transfers (uploads & downloads) will be
+performed via a singular HTTP resource and that the URLs provided in the
+response are implemented as such. In this case each object is uploaded or
+downloaded in its entirety through that one URL.
+
+However, in order to support more advanced transfer features such as resuming,
+chunking or delegation to other services, the client can indicate in the request
+its ability to handle other transfer mechanisms. 
+
+Here's a possible example:
+
+```json
+{
+  "operation": "upload",
+  "accept-transfers": "tus,resumable.js",
+  "objects": [
+    {
+      "oid": "1111111",
+      "size": 123
+    }
+  ]
+}
+```
+
+The `accept-transfers` field is a comma-separated list of identifiers which the
+client is able to support, in order of preference. In this hypothetical example
+the client is indicating it is able to support resumable uploads using either
+the tus.io protocol, or the resumable.js protocol. It is implicit that basic
+HTTP resources are always supported regardless of the presence or content of
+this item.
+
+If the server is able to support one of the extended transfer mechanisms, it can
+provide resources specific to that mechanism in the response, with an indicator
+of which one it picked:
+
+```json
+{
+  "transfer": "tus",
+  "objects": [
+   {
+      "oid": "1111111",
+      "size": 123,
+      "actions": {
+        "upload": {
+          "href": "https://my.tus.server.com/files/1111111"
+        }
+      }
+    }
+  ]
+}
+```
+
+In this case the server has chosen [tus.io](http://tus.io); in this case the
+underlying transport is still HTTP, so the `href` is still a web URL, but the
+exact sequence of calls and the headers sent & received are different from a
+single resource upload. Other transfers may use other protocols.
+
+__Note__: these API features are provided for future extension and the examples
+shown may not represent actual features present in the current client).