From f02c9350e9fb5c65af83c566bb3d3d9cc9ebab1e Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sat, 11 Oct 2014 23:00:59 -0700 Subject: [PATCH 01/67] Create attachment.md --- attachment.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 attachment.md diff --git a/attachment.md b/attachment.md new file mode 100644 index 0000000..92ddb12 --- /dev/null +++ b/attachment.md @@ -0,0 +1,127 @@ +# Attachment +This document outlines an extension which supports sending and receiving CollectionJson documents containing file attachments. This approach uses a multipart/form-data request/response as a means of transfering attachments back and forth. + +*Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). + +It based on this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) + +## Attachment template +A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. Each attachment will be indicated with a _file_ attribute. + +### File data element +A new _file_ attribute is introduced on the data element. For a template, this indicates that this data element is a file. + +### Example +```javascript +{ + "template" : { + "data" : [ + {"name" : "full-name", "value" : ""}, + {"name" : "email", "value" : ""}, + {"name" : "avatar", "file": ""} + ] + } +} +``` +## Sending attachments +A client may send a response that contains attachments using the media type "multipart/form-data". It contains parts with a CollectionJson template populated with data as well as attachments. + +### Parts +* The first part in the document will be a CollectionJson template. +* The document part must have a _name_ of "template" in it's content-disposition header +* All additional parts will be attachments. +* Each attachment may have a "name" as part of the content-disposition header which matches the name in the template. + +## File data element +A _file_ element of the template indicates that the client should send an attachment. + +### Example +Below you can can see the request contains a write template with contact information. The template contains an avatar _file_ item. There is an additional part which contains the avatar image which has a _name_ of 'avatar' +``` +Content-Type: multipart/form-data, boundary=AaB03x +Content-Type: application/vnd.collection+json +--AaB03x +Content-Disposition: form-data; name="template" + +{ + "template" : { + "data" : [ + {"name" : "full-name", "value" : "John Doe"}, + {"name" : "email", "value" : "jdoe@example.org"}, + {"name" : "avatar", "file": ""} + ] + } +} +--AaB03x +Content-Disposition: form-data; name="document" +Content-Type: application/vnd.collection+json + +--AaB03x +Content-Disposition: attachment; name="avatar"; filename="johndoe.jpeg" +Content-Type: image/jpeg +Content-Transfer-Encoding: binary +... + +--AaB03x +``` +## Receving attachments +A client may also receive a response that contains attachments. In these cases the response media type will be "multipart/form-data" containing parts for a CollectionJson document as well as attachments. + +### Parts +* The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. +* The document part must have a "name" of "document" as it's content-disposition header +* All additional parts will be attachments which relate to the document. +* Each attachment must have a "name" as part of the content-disposition header. + +### File Data element +The _file_ element in the response indicates that this item has an associated attachment. The _value_ of the file matches the _name_ attribute of the Content-Disposition header in one of the parts. + +### Example +Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has a _file_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. + +``` +Content-type: multipart/form-data, boundary=AaB03x + +--AaB03x +Content-Disposition: form-data; name="document" +Content-Type: application/vnd.collection+json +{ "collection" : + { + "version" : "1.0", + "href" : "http://example.org/friends/", + + "items" : [ + { + "href" : "http://example.org/friends/jdoe", + "data" : [ + {"name" : "full-name", "value" : "John Doe", "prompt" : "Full Name"}, + {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} + {"name" : "avatar", "file" : "jdoe"} + ] + }, + { + "href" : "http://example.org/friends/mamund", + "data" : [ + {"name" : "full-name", "value" : "Mike Amundsen", "prompt" : "Full Name"}, + {"name" : "email", "value" : "mca@amundsen.com", "prompt" : "Email"} + {"name" : "avatar", "file" : "mamund"} + ] + } + } + } +} + +--AaB03x +Content-Disposition: attachment; name="jdoe"; filename="johndoe.jpeg" +Content-Type: image/jpeg +Content-Transfer-Encoding: binary +... + +--AaB03x +Content-Disposition: attachment; name="mamund"; filename="mikeamundsen.jpeg" +Content-Type: image/jpeg +Content-Transfer-Encoding: binary +... + +--AaB03x +``` From b391e7c1fe5401a76fcdd0bceafdea3020887bc2 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sat, 11 Oct 2014 23:08:12 -0700 Subject: [PATCH 02/67] Update attachment.md --- attachment.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/attachment.md b/attachment.md index 92ddb12..8335f2d 100644 --- a/attachment.md +++ b/attachment.md @@ -8,8 +8,8 @@ It based on this [discussion](https://groups.google.com/forum/#!topic/collection ## Attachment template A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. Each attachment will be indicated with a _file_ attribute. -### File data element -A new _file_ attribute is introduced on the data element. For a template, this indicates that this data element is a file. +### Attachment data element +A new _attachment_ attribute is introduced on the data element. For a template, this indicates that this data element is an attachment. ### Example ```javascript @@ -18,7 +18,7 @@ A new _file_ attribute is introduced on the data element. For a template, this i "data" : [ {"name" : "full-name", "value" : ""}, {"name" : "email", "value" : ""}, - {"name" : "avatar", "file": ""} + {"name" : "avatar", "attachment": ""} ] } } @@ -36,7 +36,7 @@ A client may send a response that contains attachments using the media type "mul A _file_ element of the template indicates that the client should send an attachment. ### Example -Below you can can see the request contains a write template with contact information. The template contains an avatar _file_ item. There is an additional part which contains the avatar image which has a _name_ of 'avatar' +Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item. There is an additional part which contains the avatar image which has a _name_ of 'avatar' ``` Content-Type: multipart/form-data, boundary=AaB03x Content-Type: application/vnd.collection+json @@ -48,7 +48,7 @@ Content-Disposition: form-data; name="template" "data" : [ {"name" : "full-name", "value" : "John Doe"}, {"name" : "email", "value" : "jdoe@example.org"}, - {"name" : "avatar", "file": ""} + {"name" : "avatar", "attachment": ""} ] } } @@ -73,8 +73,8 @@ A client may also receive a response that contains attachments. In these cases t * All additional parts will be attachments which relate to the document. * Each attachment must have a "name" as part of the content-disposition header. -### File Data element -The _file_ element in the response indicates that this item has an associated attachment. The _value_ of the file matches the _name_ attribute of the Content-Disposition header in one of the parts. +### Attachment Data element +The _attachment_ element in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. ### Example Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has a _file_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. @@ -96,7 +96,7 @@ Content-Type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "John Doe", "prompt" : "Full Name"}, {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} - {"name" : "avatar", "file" : "jdoe"} + {"name" : "avatar", "attachment" : "jdoe"} ] }, { @@ -104,7 +104,7 @@ Content-Type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "Mike Amundsen", "prompt" : "Full Name"}, {"name" : "email", "value" : "mca@amundsen.com", "prompt" : "Email"} - {"name" : "avatar", "file" : "mamund"} + {"name" : "avatar", "attachment" : "mamund"} ] } } @@ -125,3 +125,4 @@ Content-Transfer-Encoding: binary --AaB03x ``` + From 0eced3da1cd30ebe4d424c7c16f0293d91322138 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sat, 11 Oct 2014 23:16:26 -0700 Subject: [PATCH 03/67] Update attachment.md --- attachment.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 8335f2d..5279d37 100644 --- a/attachment.md +++ b/attachment.md @@ -28,6 +28,7 @@ A client may send a response that contains attachments using the media type "mul ### Parts * The first part in the document will be a CollectionJson template. +* All _attachment_ fields in the data element must have a value set to the name in the content-disposition header of the corresponding part. * The document part must have a _name_ of "template" in it's content-disposition header * All additional parts will be attachments. * Each attachment may have a "name" as part of the content-disposition header which matches the name in the template. @@ -48,7 +49,7 @@ Content-Disposition: form-data; name="template" "data" : [ {"name" : "full-name", "value" : "John Doe"}, {"name" : "email", "value" : "jdoe@example.org"}, - {"name" : "avatar", "attachment": ""} + {"name" : "avatar", "attachment": "jdoe"} ] } } @@ -57,7 +58,7 @@ Content-Disposition: form-data; name="document" Content-Type: application/vnd.collection+json --AaB03x -Content-Disposition: attachment; name="avatar"; filename="johndoe.jpeg" +Content-Disposition: attachment; name="jdoe"; filename="johndoe.jpeg" Content-Type: image/jpeg Content-Transfer-Encoding: binary ... From e3b92e84212ff3c098929fcc5a21d508e55156fc Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sat, 11 Oct 2014 23:19:33 -0700 Subject: [PATCH 04/67] Update attachment.md --- attachment.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/attachment.md b/attachment.md index 5279d37..6f059de 100644 --- a/attachment.md +++ b/attachment.md @@ -8,8 +8,8 @@ It based on this [discussion](https://groups.google.com/forum/#!topic/collection ## Attachment template A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. Each attachment will be indicated with a _file_ attribute. -### Attachment data element -A new _attachment_ attribute is introduced on the data element. For a template, this indicates that this data element is an attachment. +### Attachment field +A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. ### Example ```javascript @@ -37,7 +37,7 @@ A client may send a response that contains attachments using the media type "mul A _file_ element of the template indicates that the client should send an attachment. ### Example -Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item. There is an additional part which contains the avatar image which has a _name_ of 'avatar' +Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'jdoe' ``` Content-Type: multipart/form-data, boundary=AaB03x Content-Type: application/vnd.collection+json @@ -70,12 +70,13 @@ A client may also receive a response that contains attachments. In these cases t ### Parts * The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. +* All _attachment_ fields in the data element must have a value set to the name in the content-disposition header of the corresponding part. * The document part must have a "name" of "document" as it's content-disposition header * All additional parts will be attachments which relate to the document. * Each attachment must have a "name" as part of the content-disposition header. ### Attachment Data element -The _attachment_ element in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. +The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. ### Example Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has a _file_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. From 63b03e3a398a64c85fea94027b5876a4f8331745 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sat, 11 Oct 2014 23:46:36 -0700 Subject: [PATCH 05/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 6f059de..b52fd9c 100644 --- a/attachment.md +++ b/attachment.md @@ -33,8 +33,8 @@ A client may send a response that contains attachments using the media type "mul * All additional parts will be attachments. * Each attachment may have a "name" as part of the content-disposition header which matches the name in the template. -## File data element -A _file_ element of the template indicates that the client should send an attachment. +## Attachment field +An _attachment_ field in a data element of the template indicates that the client should send an attachment. ### Example Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'jdoe' From e93235b923545fe500ab18b2dabb224d01954988 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 00:51:36 -0700 Subject: [PATCH 06/67] Update attachment.md --- attachment.md | 65 +++++++++++++++++++-------------------------------- 1 file changed, 24 insertions(+), 41 deletions(-) diff --git a/attachment.md b/attachment.md index b52fd9c..d337ca4 100644 --- a/attachment.md +++ b/attachment.md @@ -6,7 +6,7 @@ This document outlines an extension which supports sending and receiving Collect It based on this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) ## Attachment template -A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. Each attachment will be indicated with a _file_ attribute. +A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. ### Attachment field A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. @@ -24,14 +24,11 @@ A new _attachment_ field is introduced on the data element. For a template, this } ``` ## Sending attachments -A client may send a response that contains attachments using the media type "multipart/form-data". It contains parts with a CollectionJson template populated with data as well as attachments. +A client may send a response that contains attachments using the media type "multipart/form-data". It contains the data for the write template as well as attachments. ### Parts -* The first part in the document will be a CollectionJson template. -* All _attachment_ fields in the data element must have a value set to the name in the content-disposition header of the corresponding part. -* The document part must have a _name_ of "template" in it's content-disposition header -* All additional parts will be attachments. -* Each attachment may have a "name" as part of the content-disposition header which matches the name in the template. +* All _attachment_ fields in the data element must have a corresponding part. +* The part must have a name matching the form element name. ## Attachment field An _attachment_ field in a data element of the template indicates that the client should send an attachment. @@ -39,34 +36,24 @@ An _attachment_ field in a data element of the template indicates that the clien ### Example Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'jdoe' ``` -Content-Type: multipart/form-data, boundary=AaB03x -Content-Type: application/vnd.collection+json ---AaB03x -Content-Disposition: form-data; name="template" +content-type: multipart/form-data, boundary=AaB03x -{ - "template" : { - "data" : [ - {"name" : "full-name", "value" : "John Doe"}, - {"name" : "email", "value" : "jdoe@example.org"}, - {"name" : "avatar", "attachment": "jdoe"} - ] - } -} --AaB03x -Content-Disposition: form-data; name="document" -Content-Type: application/vnd.collection+json - +content-disposition: form-data; name="full-name" +content-type: text/plain; charset=us-ascii +John Doe +--AaB03x +content-disposition: form-data; name="email" +content-type: text/plain; charset=us-ascii +jdoe@example.org --AaB03x -Content-Disposition: attachment; name="jdoe"; filename="johndoe.jpeg" -Content-Type: image/jpeg -Content-Transfer-Encoding: binary +content-disposition: form-data; name="avatar" +content-type: image/jpeg ... - --AaB03x ``` ## Receving attachments -A client may also receive a response that contains attachments. In these cases the response media type will be "multipart/form-data" containing parts for a CollectionJson document as well as attachments. +A client may also receive a response that contains attachments. In these cases the response media type will be "multipart/mixed" containing parts for a collection+json document as well as attachments. ### Parts * The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. @@ -79,14 +66,13 @@ A client may also receive a response that contains attachments. In these cases t The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. ### Example -Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has a _file_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. +Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an _attachment_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. ``` -Content-type: multipart/form-data, boundary=AaB03x +content-type: multipart/mixed, boundary=AaB03x --AaB03x -Content-Disposition: form-data; name="document" -Content-Type: application/vnd.collection+json +content-type: application/vnd.collection+json { "collection" : { "version" : "1.0", @@ -112,19 +98,16 @@ Content-Type: application/vnd.collection+json } } } - --AaB03x -Content-Disposition: attachment; name="jdoe"; filename="johndoe.jpeg" -Content-Type: image/jpeg -Content-Transfer-Encoding: binary +content-disposition: attachment; filename="jdoe.jpeg"; name="jdoe"; +content-type: image/jpeg +content-transfer-encoding: binary ... - --AaB03x -Content-Disposition: attachment; name="mamund"; filename="mikeamundsen.jpeg" -Content-Type: image/jpeg -Content-Transfer-Encoding: binary +content-disposition: attachment; filename="mamund.jpeg"; name="mamund"; +content-type: image/jpeg +content-transfer-Encoding: binary ... - --AaB03x ``` From 6dda53c964535ff9f608e5eab670d0095c89ea5c Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 00:54:12 -0700 Subject: [PATCH 07/67] Update attachment.md --- attachment.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/attachment.md b/attachment.md index d337ca4..cad1c17 100644 --- a/attachment.md +++ b/attachment.md @@ -66,7 +66,7 @@ A client may also receive a response that contains attachments. In these cases t The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. ### Example -Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an _attachment_ element. Then there are additional parts which are the actual attachments. Each one has a _name_ which the CollectionJson document uses as the key. +Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the CollectionJson document. ``` content-type: multipart/mixed, boundary=AaB03x @@ -84,7 +84,7 @@ content-type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "John Doe", "prompt" : "Full Name"}, {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} - {"name" : "avatar", "attachment" : "jdoe"} + {"name" : "avatar", "attachment" : "jdoe.jpg"} ] }, { @@ -92,19 +92,19 @@ content-type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "Mike Amundsen", "prompt" : "Full Name"}, {"name" : "email", "value" : "mca@amundsen.com", "prompt" : "Email"} - {"name" : "avatar", "attachment" : "mamund"} + {"name" : "avatar", "attachment" : "mamund.jpg"} ] } } } } --AaB03x -content-disposition: attachment; filename="jdoe.jpeg"; name="jdoe"; +content-disposition: attachment; filename="jdoe.jpeg" content-type: image/jpeg content-transfer-encoding: binary ... --AaB03x -content-disposition: attachment; filename="mamund.jpeg"; name="mamund"; +content-disposition: attachment; filename="mamund.jpeg" content-type: image/jpeg content-transfer-Encoding: binary ... From c3b93a99e11af2bd49983a11b54fcd8fca26b185 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 00:55:05 -0700 Subject: [PATCH 08/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index cad1c17..53bca0d 100644 --- a/attachment.md +++ b/attachment.md @@ -30,7 +30,7 @@ A client may send a response that contains attachments using the media type "mul * All _attachment_ fields in the data element must have a corresponding part. * The part must have a name matching the form element name. -## Attachment field +### Attachment field An _attachment_ field in a data element of the template indicates that the client should send an attachment. ### Example From 039d474c62136367e15039be3903f05fb46a3dd2 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 00:56:07 -0700 Subject: [PATCH 09/67] Update attachment.md --- attachment.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/attachment.md b/attachment.md index 53bca0d..6c87f50 100644 --- a/attachment.md +++ b/attachment.md @@ -30,9 +30,6 @@ A client may send a response that contains attachments using the media type "mul * All _attachment_ fields in the data element must have a corresponding part. * The part must have a name matching the form element name. -### Attachment field -An _attachment_ field in a data element of the template indicates that the client should send an attachment. - ### Example Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'jdoe' ``` From 69a83563fd05b9f271a32332720721f99e37a047 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 00:56:34 -0700 Subject: [PATCH 10/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 6c87f50..2fa4caa 100644 --- a/attachment.md +++ b/attachment.md @@ -59,7 +59,7 @@ A client may also receive a response that contains attachments. In these cases t * All additional parts will be attachments which relate to the document. * Each attachment must have a "name" as part of the content-disposition header. -### Attachment Data element +### Attachment Data field The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. ### Example From c2e585011b46bb9bf55e08735f15c0688dca1314 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:03:25 -0700 Subject: [PATCH 11/67] Update attachment.md --- attachment.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 2fa4caa..e8abbe7 100644 --- a/attachment.md +++ b/attachment.md @@ -3,7 +3,13 @@ This document outlines an extension which supports sending and receiving Collect *Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). -It based on this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) +It is inspired by this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) + +The following RFCs form the basis of the approach in this document: + +* [1341] (http://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) - The Multipart Content-Type +* [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data +* [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) ## Attachment template A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. From 1be83950ac7989d4b26de636a36469bdcbbf993a Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:03:44 -0700 Subject: [PATCH 12/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index e8abbe7..494dd5c 100644 --- a/attachment.md +++ b/attachment.md @@ -1,4 +1,4 @@ -# Attachment +# Attachment extension This document outlines an extension which supports sending and receiving CollectionJson documents containing file attachments. This approach uses a multipart/form-data request/response as a means of transfering attachments back and forth. *Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). From 520087b146b847c793056cb9c7a5fdc1ab620182 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:04:19 -0700 Subject: [PATCH 13/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 494dd5c..73739a7 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This document outlines an extension which supports sending and receiving CollectionJson documents containing file attachments. This approach uses a multipart/form-data request/response as a means of transfering attachments back and forth. +This document outlines an extension which supports sending and receiving CollectionJson documents containing file attachments. This approach uses a multipart/form-data request / multipart/mixed response as a means of transfering attachments back and forth. *Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). From 9a7552dd7bb2d33abb41298d6fb88a4ef4078262 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:05:55 -0700 Subject: [PATCH 14/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 73739a7..95fffca 100644 --- a/attachment.md +++ b/attachment.md @@ -11,8 +11,8 @@ The following RFCs form the basis of the approach in this document: * [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) -## Attachment template -A client may receive a CollectionJson document containing a template which accepts attachments which the client can use to send files. +## Write template +A client may receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. ### Attachment field A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. From e1e50304deb242ac3eb80aa51c80df0114ca9e98 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:17:32 -0700 Subject: [PATCH 15/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 95fffca..e1be4f9 100644 --- a/attachment.md +++ b/attachment.md @@ -30,7 +30,7 @@ A new _attachment_ field is introduced on the data element. For a template, this } ``` ## Sending attachments -A client may send a response that contains attachments using the media type "multipart/form-data". It contains the data for the write template as well as attachments. +A client may send a request that contains attachments using the media type "multipart/form-data". It contains the data for the write template as well as attachments. ### Parts * All _attachment_ fields in the data element must have a corresponding part. From d0938f39c17ee2596015b99b75d88401bf000d8f Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 01:41:50 -0700 Subject: [PATCH 16/67] Update attachment.md --- attachment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/attachment.md b/attachment.md index e1be4f9..dfd7445 100644 --- a/attachment.md +++ b/attachment.md @@ -15,7 +15,7 @@ The following RFCs form the basis of the approach in this document: A client may receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. ### Attachment field -A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. +A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. The value of the attachment is the mime type that is expected. ### Example ```javascript @@ -24,7 +24,7 @@ A new _attachment_ field is introduced on the data element. For a template, this "data" : [ {"name" : "full-name", "value" : ""}, {"name" : "email", "value" : ""}, - {"name" : "avatar", "attachment": ""} + {"name" : "avatar", "attachment": "image/jpeg"} ] } } @@ -66,7 +66,7 @@ A client may also receive a response that contains attachments. In these cases t * Each attachment must have a "name" as part of the content-disposition header. ### Attachment Data field -The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the _name_ attribute of the Content-Disposition header in one of the parts. +The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the filename in the content-disposition header in one of the parts. ### Example Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the CollectionJson document. From fb64e280b21f25a8cad34bcaa71bf9058782b0eb Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:19:54 -0700 Subject: [PATCH 17/67] Update attachment.md --- attachment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/attachment.md b/attachment.md index dfd7445..50befa0 100644 --- a/attachment.md +++ b/attachment.md @@ -114,3 +114,4 @@ content-transfer-Encoding: binary --AaB03x ``` +To see a real response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16) From 51c14a028cb7b614cf31d7d77aa6e23878aa7e4d Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:20:35 -0700 Subject: [PATCH 18/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 50befa0..34ff495 100644 --- a/attachment.md +++ b/attachment.md @@ -114,4 +114,4 @@ content-transfer-Encoding: binary --AaB03x ``` -To see a real response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16) +To see a real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16) From 0bfb4cc5ed83a384dd148e1ed66a86c8bf1eed6b Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:23:12 -0700 Subject: [PATCH 19/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 34ff495..4ad435d 100644 --- a/attachment.md +++ b/attachment.md @@ -114,4 +114,4 @@ content-transfer-Encoding: binary --AaB03x ``` -To see a real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16) +To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/) with a tool like Fiddler. From 408f82cabc33fca43bb600a3a1126ac0bb9a6d92 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:23:37 -0700 Subject: [PATCH 20/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 4ad435d..228c59e 100644 --- a/attachment.md +++ b/attachment.md @@ -114,4 +114,4 @@ content-transfer-Encoding: binary --AaB03x ``` -To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/) with a tool like Fiddler. +To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler. From a9817291d3e20dab226840d8b94a635be2174e23 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:42:25 -0700 Subject: [PATCH 21/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 228c59e..27d55da 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This document outlines an extension which supports sending and receiving CollectionJson documents containing file attachments. This approach uses a multipart/form-data request / multipart/mixed response as a means of transfering attachments back and forth. +This document outlines an extension which supports sending and receiving collection+json documents containing file attachments. This approach uses a multipart/form-data request / multipart/mixed response as a means of transfering attachments back and forth. *Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). From a2c063009eedc13f5c3c9043e9d924b48395496f Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 02:42:50 -0700 Subject: [PATCH 22/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 27d55da..0328b86 100644 --- a/attachment.md +++ b/attachment.md @@ -114,4 +114,4 @@ content-transfer-Encoding: binary --AaB03x ``` -To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler. +To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler or using curl: `curl http://cj-attachment.azurewebsites.net/friend -v` From 6a8f54d206122a1f6b8d2ccf42349d10b5221f23 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 11:26:54 -0700 Subject: [PATCH 23/67] Update attachment.md --- attachment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/attachment.md b/attachment.md index 0328b86..e8dc941 100644 --- a/attachment.md +++ b/attachment.md @@ -34,10 +34,10 @@ A client may send a request that contains attachments using the media type "mult ### Parts * All _attachment_ fields in the data element must have a corresponding part. -* The part must have a name matching the form element name. +* The part must have a filename. ### Example -Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'jdoe' +Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'avatar' and a filename of "jdoe.jpg". ``` content-type: multipart/form-data, boundary=AaB03x @@ -50,7 +50,7 @@ content-disposition: form-data; name="email" content-type: text/plain; charset=us-ascii jdoe@example.org --AaB03x -content-disposition: form-data; name="avatar" +content-disposition: form-data; name="avatar"; filename="jdoe.jpg" content-type: image/jpeg ... --AaB03x From 721d14a33548ad63f25c0d7f463eec83d44775cc Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 11:32:09 -0700 Subject: [PATCH 24/67] Update attachment.md --- attachment.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index e8dc941..7f80dee 100644 --- a/attachment.md +++ b/attachment.md @@ -56,7 +56,11 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client may also receive a response that contains attachments. In these cases the response media type will be "multipart/mixed" containing parts for a collection+json document as well as attachments. +A client may also receive a response that contains attachments. + +* If the client sends an accept header of "multipart/mixed", the response media type will be "multipart/mixed" containing parts for a collection+json document as well as attachments. + +* If the client sends an accept header of "application/vnd.collection+json", the response will be as expected, a collection+json document. However, the items within the document will have _attachment_ fields (see the **Attachment Data Field** section) to indicate to the client that they can do a multipart request. ### Parts * The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. From e93abb549608bbfbae704328d64f922efe8ee201 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 11:38:18 -0700 Subject: [PATCH 25/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 7f80dee..ff23b67 100644 --- a/attachment.md +++ b/attachment.md @@ -60,7 +60,7 @@ A client may also receive a response that contains attachments. * If the client sends an accept header of "multipart/mixed", the response media type will be "multipart/mixed" containing parts for a collection+json document as well as attachments. -* If the client sends an accept header of "application/vnd.collection+json", the response will be as expected, a collection+json document. However, the items within the document will have _attachment_ fields (see the **Attachment Data Field** section) to indicate to the client that they can do a multipart request. +* If the client sends an accept header of "application/vnd.collection+json", the response will be as expected, a collection+json document. However, if there are attachments, the items within the document will have _attachment_ fields (see the **Attachment Data Field** section) to indicate to the client that they can do a multipart request. ### Parts * The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. From 2215c4d4043084a6c7e637e1e06787a6230ee780 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 20:17:39 -0700 Subject: [PATCH 26/67] Update attachment.md --- attachment.md | 37 +++++++------------------------------ 1 file changed, 7 insertions(+), 30 deletions(-) diff --git a/attachment.md b/attachment.md index ff23b67..a5014eb 100644 --- a/attachment.md +++ b/attachment.md @@ -56,29 +56,12 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client may also receive a response that contains attachments. - -* If the client sends an accept header of "multipart/mixed", the response media type will be "multipart/mixed" containing parts for a collection+json document as well as attachments. - -* If the client sends an accept header of "application/vnd.collection+json", the response will be as expected, a collection+json document. However, if there are attachments, the items within the document will have _attachment_ fields (see the **Attachment Data Field** section) to indicate to the client that they can do a multipart request. - -### Parts -* The first part in the document will be a CollectionJson document. The document will contain pointers back to the attachments in the response. -* All _attachment_ fields in the data element must have a value set to the name in the content-disposition header of the corresponding part. -* The document part must have a "name" of "document" as it's content-disposition header -* All additional parts will be attachments which relate to the document. -* Each attachment must have a "name" as part of the content-disposition header. - -### Attachment Data field -The _attachment_ field in the response indicates that this item has an associated attachment. The _value_ of the attachment matches the filename in the content-disposition header in one of the parts. +A client may also receive a response that items which contain attachments. Attachments are indicated by a link with a rel of "enclosure". This indicates that href points to a file which should be downloaded. ### Example Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the CollectionJson document. ``` -content-type: multipart/mixed, boundary=AaB03x - ---AaB03x content-type: application/vnd.collection+json { "collection" : { @@ -92,6 +75,9 @@ content-type: application/vnd.collection+json {"name" : "full-name", "value" : "John Doe", "prompt" : "Full Name"}, {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} {"name" : "avatar", "attachment" : "jdoe.jpg"} + ], + "links": [ + {"name": "avatar", "rel": "enclosure", "href":"http://example.org/images/jdoe.jpg"} ] }, { @@ -99,23 +85,14 @@ content-type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "Mike Amundsen", "prompt" : "Full Name"}, {"name" : "email", "value" : "mca@amundsen.com", "prompt" : "Email"} - {"name" : "avatar", "attachment" : "mamund.jpg"} + ], + "links": [ + {"name": "avatar", "rel": "enclosure", "href":"http://example.org/images/mamund.jpg"} ] } } } } ---AaB03x -content-disposition: attachment; filename="jdoe.jpeg" -content-type: image/jpeg -content-transfer-encoding: binary -... ---AaB03x -content-disposition: attachment; filename="mamund.jpeg" -content-type: image/jpeg -content-transfer-Encoding: binary -... ---AaB03x ``` To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler or using curl: `curl http://cj-attachment.azurewebsites.net/friend -v` From f6417daf059cb8a0f7ffa9bfe40fb4dd3b2db104 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 20:18:19 -0700 Subject: [PATCH 27/67] Update attachment.md --- attachment.md | 1 - 1 file changed, 1 deletion(-) diff --git a/attachment.md b/attachment.md index a5014eb..662f635 100644 --- a/attachment.md +++ b/attachment.md @@ -74,7 +74,6 @@ content-type: application/vnd.collection+json "data" : [ {"name" : "full-name", "value" : "John Doe", "prompt" : "Full Name"}, {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} - {"name" : "avatar", "attachment" : "jdoe.jpg"} ], "links": [ {"name": "avatar", "rel": "enclosure", "href":"http://example.org/images/jdoe.jpg"} From bcd8749991842799b46fd80d02abe2636087bfac Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 22:25:03 -0700 Subject: [PATCH 28/67] Update attachment.md --- attachment.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/attachment.md b/attachment.md index 662f635..a079bb6 100644 --- a/attachment.md +++ b/attachment.md @@ -14,27 +14,37 @@ The following RFCs form the basis of the approach in this document: ## Write template A client may receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. +### enc-type field +A new _enc-type_ field is introduced on the template element. +* It MUST have a value of "application/json", "application/vnd.collection+json", or "multipart/form-data". +* For templates with attachments, "multipart/form-data" MUST be used. + ### Attachment field -A new _attachment_ field is introduced on the data element. For a template, this indicates that this data element is an attachment. The value of the attachment is the mime type that is expected. +A new _attachment_ field is introduced on the data element. +* This field MUST be set to "true" to indicate to the client that this is an attachment. +** If _enc-type_ is not present / is not set to "multipart/form-data" then clients MUST treat it as text. +** If _attachment_ is set to false, then clients MUST treat it as text. ### Example ```javascript { "template" : { + "enc-type" : "multipart/form-data", "data" : [ {"name" : "full-name", "value" : ""}, {"name" : "email", "value" : ""}, - {"name" : "avatar", "attachment": "image/jpeg"} + {"name" : "avatar", "attachment": "true"} ] } } ``` ## Sending attachments -A client may send a request that contains attachments using the media type "multipart/form-data". It contains the data for the write template as well as attachments. +A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template as well as attachments. ### Parts -* All _attachment_ fields in the data element must have a corresponding part. -* The part must have a filename. +* Items with _attachment_ fields in the data element MAY have a corresponding part. +* If there is a corresponding part, then it MUST match the name of a data element in the template. +** If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. ### Example Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'avatar' and a filename of "jdoe.jpg". @@ -56,10 +66,10 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client may also receive a response that items which contain attachments. Attachments are indicated by a link with a rel of "enclosure". This indicates that href points to a file which should be downloaded. +A client may also receive a response that items which contain attachments. Attachments are indicated by a link with a render value of "attachment". This indicates that href points to a file which should be downloaded. ### Example -Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the CollectionJson document. +Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the collection+json document. ``` content-type: application/vnd.collection+json @@ -76,7 +86,7 @@ content-type: application/vnd.collection+json {"name" : "email", "value" : "jdoe@example.org", "prompt" : "Email"} ], "links": [ - {"name": "avatar", "rel": "enclosure", "href":"http://example.org/images/jdoe.jpg"} + {"name": "avatar", "rel": "related", "render": "attachment", "href":"http://example.org/images/jdoe.jpg"} ] }, { @@ -86,7 +96,7 @@ content-type: application/vnd.collection+json {"name" : "email", "value" : "mca@amundsen.com", "prompt" : "Email"} ], "links": [ - {"name": "avatar", "rel": "enclosure", "href":"http://example.org/images/mamund.jpg"} + {"name": "avatar", "rel": "related", "render": "attachment", "href":"http://example.org/images/mamund.jpg"} ] } } @@ -94,4 +104,6 @@ content-type: application/vnd.collection+json } ``` +**Note** - The server below / gist is currently not up to date with the spec. + To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler or using curl: `curl http://cj-attachment.azurewebsites.net/friend -v` From 8fc28a16bf67f054a9dc47dc95c85d8d4c9b101b Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 22:25:58 -0700 Subject: [PATCH 29/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index a079bb6..d651c53 100644 --- a/attachment.md +++ b/attachment.md @@ -19,7 +19,7 @@ A new _enc-type_ field is introduced on the template element. * It MUST have a value of "application/json", "application/vnd.collection+json", or "multipart/form-data". * For templates with attachments, "multipart/form-data" MUST be used. -### Attachment field +### attachment field A new _attachment_ field is introduced on the data element. * This field MUST be set to "true" to indicate to the client that this is an attachment. ** If _enc-type_ is not present / is not set to "multipart/form-data" then clients MUST treat it as text. From 982693cc58dd2c81f3a3029f5648d1305680efc8 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Sun, 12 Oct 2014 22:26:59 -0700 Subject: [PATCH 30/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index d651c53..17a6fcd 100644 --- a/attachment.md +++ b/attachment.md @@ -12,7 +12,7 @@ The following RFCs form the basis of the approach in this document: * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) ## Write template -A client may receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. +A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. ### enc-type field A new _enc-type_ field is introduced on the template element. @@ -66,7 +66,7 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client may also receive a response that items which contain attachments. Attachments are indicated by a link with a render value of "attachment". This indicates that href points to a file which should be downloaded. +A client MAY also receive a response that items which contain attachments. Attachments are indicated by a link with a render value of "attachment". This indicates that href points to a file which SHOULD be downloaded. ### Example Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the collection+json document. From bcc4eefd969b982a47540a98e69136f6b11f1286 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Mon, 13 Oct 2014 15:03:44 -0700 Subject: [PATCH 31/67] Update attachment.md --- attachment.md | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/attachment.md b/attachment.md index 17a6fcd..0fe7111 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This document outlines an extension which supports sending and receiving collection+json documents containing file attachments. This approach uses a multipart/form-data request / multipart/mixed response as a means of transfering attachments back and forth. +This extension outlines an extension which supports sending and receiving `collection+json` documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. *Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). @@ -11,25 +11,33 @@ The following RFCs form the basis of the approach in this document: * [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) +## Live example +* To see a live response containing attachments, use the following command: `curl http://cj-attachment.azurewebsites.net/friend -v` + ## Write template A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. -### enc-type field -A new _enc-type_ field is introduced on the template element. -* It MUST have a value of "application/json", "application/vnd.collection+json", or "multipart/form-data". -* For templates with attachments, "multipart/form-data" MUST be used. +### content-type field +This extension defines a new optional property for the template object: `content-type`. The two valid values for `content-type ` are: + +* `multipart/form-data` (this is the one to use for uploading attachments) +* `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. ### attachment field -A new _attachment_ field is introduced on the data element. -* This field MUST be set to "true" to indicate to the client that this is an attachment. -** If _enc-type_ is not present / is not set to "multipart/form-data" then clients MUST treat it as text. -** If _attachment_ is set to false, then clients MUST treat it as text. +This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. + +The two valid values for the `attachment` property: + +* true (treat this data element as an attachment to be uploaded) +* false (treat this data element as a text element) If the client does not support the attachment property and/or the value of this property is not understood, the client MUST treat the data element as a text element. ### Example +Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment. + ```javascript { "template" : { - "enc-type" : "multipart/form-data", + "content-type" : "multipart/form-data", "data" : [ {"name" : "full-name", "value" : ""}, {"name" : "email", "value" : ""}, @@ -41,13 +49,13 @@ A new _attachment_ field is introduced on the data element. ## Sending attachments A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template as well as attachments. -### Parts -* Items with _attachment_ fields in the data element MAY have a corresponding part. -* If there is a corresponding part, then it MUST match the name of a data element in the template. +### Attachment Body Parts +* Items with _attachment_ fields in the data element MAY have a corresponding body part in the multipart request. +* For the part to be corresponding, it MUST match the name of a data element in the template. ** If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. ### Example -Below you can can see the request contains a write template with contact information. The template contains an avatar _attachment_ item with the value of the attachment being 'jdoe'. There is an additional part which contains the avatar image which has a _name_ of 'avatar' and a filename of "jdoe.jpg". +Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. ``` content-type: multipart/form-data, boundary=AaB03x @@ -66,10 +74,10 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client MAY also receive a response that items which contain attachments. Attachments are indicated by a link with a render value of "attachment". This indicates that href points to a file which SHOULD be downloaded. +A client MAY receive a response which contains links with the `render` property set to `attachment`. The client SHOULD treat the associated href as a download-able link. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example -Below is an example of a response containing attachments. The first part is a document which contains the list of contacts where each contact has an avatar with an _attachment_ field. Then there are additional parts which are the actual attachments. Each attachment's filename corresponds to the value of the _attachment_ field for the item in the collection+json document. +Below is an example of a response containing links which are attachments, namely the `avatar` link has a `render` value of `attachemnt`. The client in this casse SHOULD download the associated image. ``` content-type: application/vnd.collection+json @@ -104,6 +112,3 @@ content-type: application/vnd.collection+json } ``` -**Note** - The server below / gist is currently not up to date with the spec. - -To see a gist with real server response with attachments go [here] (https://gist.github.com/glennblock/8db0d1facb69af67af16). You can also hit a live version [here] (http://cj-attachment.azurewebsites.net/friend) with a tool like Fiddler or using curl: `curl http://cj-attachment.azurewebsites.net/friend -v` From b30afd37299ece2c1b25d098ae9ac753207ade94 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Mon, 13 Oct 2014 15:09:26 -0700 Subject: [PATCH 32/67] Update attachment.md --- attachment.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 0fe7111..30109a2 100644 --- a/attachment.md +++ b/attachment.md @@ -74,10 +74,13 @@ content-type: image/jpeg --AaB03x ``` ## Receving attachments -A client MAY receive a response which contains links with the `render` property set to `attachment`. The client SHOULD treat the associated href as a download-able link. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. +A client MAY receive a response which contains links which represent downloadable attachments. + +## attachment render value +A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example -Below is an example of a response containing links which are attachments, namely the `avatar` link has a `render` value of `attachemnt`. The client in this casse SHOULD download the associated image. +Below is an example of a response containing links which are attachments, namely the `avatar` link has a `render` value of `attachment`. The client in this casse SHOULD download the associated image. ``` content-type: application/vnd.collection+json From 097cc05b21a23fe2824d578d245dfe4ecf37c1b9 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Mon, 13 Oct 2014 15:10:06 -0700 Subject: [PATCH 33/67] Update attachment.md --- attachment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/attachment.md b/attachment.md index 30109a2..7d10154 100644 --- a/attachment.md +++ b/attachment.md @@ -17,13 +17,13 @@ The following RFCs form the basis of the approach in this document: ## Write template A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. -### content-type field +### Content-type field This extension defines a new optional property for the template object: `content-type`. The two valid values for `content-type ` are: * `multipart/form-data` (this is the one to use for uploading attachments) * `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. -### attachment field +### Attachment field This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. The two valid values for the `attachment` property: @@ -76,7 +76,7 @@ content-type: image/jpeg ## Receving attachments A client MAY receive a response which contains links which represent downloadable attachments. -## attachment render value +## Attachment render value A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example From 638e0342b2d3b3edba1a87b13d22bc2548d23c0b Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Mon, 13 Oct 2014 15:12:11 -0700 Subject: [PATCH 34/67] Update attachment.md --- attachment.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/attachment.md b/attachment.md index 7d10154..6f6e3d9 100644 --- a/attachment.md +++ b/attachment.md @@ -17,19 +17,19 @@ The following RFCs form the basis of the approach in this document: ## Write template A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. -### Content-type field +### Content-type property This extension defines a new optional property for the template object: `content-type`. The two valid values for `content-type ` are: * `multipart/form-data` (this is the one to use for uploading attachments) * `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. -### Attachment field +### Attachment property This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. The two valid values for the `attachment` property: * true (treat this data element as an attachment to be uploaded) -* false (treat this data element as a text element) If the client does not support the attachment property and/or the value of this property is not understood, the client MUST treat the data element as a text element. +* false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. ### Example Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment. @@ -50,7 +50,7 @@ Below you can can see the request contains a friend write template which specifi A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template as well as attachments. ### Attachment Body Parts -* Items with _attachment_ fields in the data element MAY have a corresponding body part in the multipart request. +* Items with `attachment` properties in the data element MAY have a corresponding body part in the multipart request. * For the part to be corresponding, it MUST match the name of a data element in the template. ** If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. From 226dda99432e62fa96f4a79ff6735df0b5a06f6a Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Mon, 13 Oct 2014 15:12:47 -0700 Subject: [PATCH 35/67] Update attachment.md --- attachment.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 6f6e3d9..41dcc94 100644 --- a/attachment.md +++ b/attachment.md @@ -51,8 +51,7 @@ A client MAY send a request that contains attachments using the media type "mult ### Attachment Body Parts * Items with `attachment` properties in the data element MAY have a corresponding body part in the multipart request. -* For the part to be corresponding, it MUST match the name of a data element in the template. -** If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. +* For the part to be corresponding, it MUST match the name of a data element in the template. If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. ### Example Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. From 0ed24f42f54cfc623f5150bc69d3b9527cc722b6 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 01:01:35 -0700 Subject: [PATCH 36/67] Updating details for live example --- attachment.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 41dcc94..0b1da53 100644 --- a/attachment.md +++ b/attachment.md @@ -12,7 +12,21 @@ The following RFCs form the basis of the approach in this document: * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) ## Live example -* To see a live response containing attachments, use the following command: `curl http://cj-attachment.azurewebsites.net/friend -v` +To see a response containing attachment links, use the following command: + +```text +curl http://cj-attachment.azurewebsites.net/friends -v +``` + +To send a multipart/form-data request with files, use the following command subsituting `thumbnail.png` with your own image. + +```text +curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" --form blog="http://example.org/jdoe" --form avatar="@./thumbnail.png" http://cj-attachment.azurewebsites.net/friends +``` + +After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. + + ## Write template A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. From ac7a3bdf8d8d18813bc24f67f1b0d1ee9fe6e84f Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 01:24:00 -0700 Subject: [PATCH 37/67] Update attachment.md --- attachment.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/attachment.md b/attachment.md index 0b1da53..7a063dd 100644 --- a/attachment.md +++ b/attachment.md @@ -18,6 +18,12 @@ To see a response containing attachment links, use the following command: curl http://cj-attachment.azurewebsites.net/friends -v ``` +You can also grab a specific friend, using the href for the item in the payload. Also you can just as well create a direct request using the shortname (first initial + last name) + +```test +curl http://cj-attachment.azurewebsites.net/friends/mamundsen +``` + To send a multipart/form-data request with files, use the following command subsituting `thumbnail.png` with your own image. ```text From b2289c044b77c38bc95ddb14caf169695efba5bb Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 01:40:40 -0700 Subject: [PATCH 38/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 7a063dd..9efa557 100644 --- a/attachment.md +++ b/attachment.md @@ -12,7 +12,7 @@ The following RFCs form the basis of the approach in this document: * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) ## Live example -To see a response containing attachment links, use the following command: +To see a response containing attachment links, use the following command or just open in a browser: ```text curl http://cj-attachment.azurewebsites.net/friends -v @@ -30,7 +30,7 @@ To send a multipart/form-data request with files, use the following command subs curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" --form blog="http://example.org/jdoe" --form avatar="@./thumbnail.png" http://cj-attachment.azurewebsites.net/friends ``` -After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. +After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. From 98976f53006ec32ef507248996cb380899e2caf3 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 19:38:12 -0700 Subject: [PATCH 39/67] Update attachment.md --- attachment.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/attachment.md b/attachment.md index 9efa557..864419e 100644 --- a/attachment.md +++ b/attachment.md @@ -32,13 +32,11 @@ curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. - - ## Write template A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. ### Content-type property -This extension defines a new optional property for the template object: `content-type`. The two valid values for `content-type ` are: +This extension defines a new optional property for the template object: `contentType`. The two valid values for `contentType ` are: * `multipart/form-data` (this is the one to use for uploading attachments) * `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. @@ -57,7 +55,7 @@ Below you can can see the request contains a friend write template which specifi ```javascript { "template" : { - "content-type" : "multipart/form-data", + "contentType" : "multipart/form-data", "data" : [ {"name" : "full-name", "value" : ""}, {"name" : "email", "value" : ""}, From 68a46e25dc344102d4a1110428a7a58310e3655b Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 19:54:51 -0700 Subject: [PATCH 40/67] Update attachment.md --- attachment.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/attachment.md b/attachment.md index 864419e..f282452 100644 --- a/attachment.md +++ b/attachment.md @@ -5,11 +5,13 @@ This extension outlines an extension which supports sending and receiving `colle It is inspired by this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) -The following RFCs form the basis of the approach in this document: +The following RFCs/documents form the basis of the approach in this document: * [1341] (http://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) - The Multipart Content-Type * [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data +* [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) - Updates to RFC2388 * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) +* ## Live example To see a response containing attachment links, use the following command or just open in a browser: @@ -50,7 +52,7 @@ The two valid values for the `attachment` property: * false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. ### Example -Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment. +Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. ```javascript { @@ -65,11 +67,12 @@ Below you can can see the request contains a friend write template which specifi } ``` ## Sending attachments -A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template as well as attachments. +A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. -### Attachment Body Parts -* Items with `attachment` properties in the data element MAY have a corresponding body part in the multipart request. -* For the part to be corresponding, it MUST match the name of a data element in the template. If a server receives a request with a part that does not match the data element, it MAY ignore the attachment. +### Mulipart requests +This extension compiles with with [RFC2388] and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. + +Note: At this time, multi-file attachements per template data object are not supported. ### Example Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. From b77b683fc9c57ec1ce7dbb220c76e6778c3b4a03 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 19:55:35 -0700 Subject: [PATCH 41/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index f282452..af9ebba 100644 --- a/attachment.md +++ b/attachment.md @@ -72,7 +72,7 @@ A client MAY send a request that contains attachments using the media type "mult ### Mulipart requests This extension compiles with with [RFC2388] and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. -Note: At this time, multi-file attachements per template data object are not supported. +**Note**: At this time, multi-file attachements per template data object are not supported. ### Example Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. From afd4a7fa8184c80231ad4d3a0b92676b49d3922d Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 19:57:11 -0700 Subject: [PATCH 42/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index af9ebba..1619bd2 100644 --- a/attachment.md +++ b/attachment.md @@ -70,7 +70,7 @@ Below you can can see the request contains a friend write template which specifi A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests -This extension compiles with with [RFC2388] and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. +This extension compiles with with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. **Note**: At this time, multi-file attachements per template data object are not supported. From 1c50b87f561e21c5c5825b7b9d5dd92b5a30c86f Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 19:58:04 -0700 Subject: [PATCH 43/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 1619bd2..84192e6 100644 --- a/attachment.md +++ b/attachment.md @@ -70,7 +70,7 @@ Below you can can see the request contains a friend write template which specifi A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests -This extension compiles with with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. +This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. **Note**: At this time, multi-file attachements per template data object are not supported. From ced21aec45a6cfceb5c4550e98bfd57f2fc2288b Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 21:43:58 -0700 Subject: [PATCH 44/67] Update attachment.md --- attachment.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/attachment.md b/attachment.md index 84192e6..27e8882 100644 --- a/attachment.md +++ b/attachment.md @@ -51,6 +51,8 @@ The two valid values for the `attachment` property: * true (treat this data element as an attachment to be uploaded) * false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. +**Note**: if the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element." + ### Example Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. From 95513757781f31f423e8fefdab39924b88d3f8af Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 21:46:36 -0700 Subject: [PATCH 45/67] Update attachment.md --- attachment.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/attachment.md b/attachment.md index 27e8882..d75af14 100644 --- a/attachment.md +++ b/attachment.md @@ -1,7 +1,7 @@ # Attachment extension This extension outlines an extension which supports sending and receiving `collection+json` documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. -*Note*: Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). +Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). It is inspired by this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) @@ -11,7 +11,10 @@ The following RFCs/documents form the basis of the approach in this document: * [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data * [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) - Updates to RFC2388 * [6266] (http://tools.ietf.org/html/rfc6266) - Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) -* + +> __NOTE:__ +> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://tools.ietf.org/html/rfc2119). + ## Live example To see a response containing attachment links, use the following command or just open in a browser: @@ -51,7 +54,8 @@ The two valid values for the `attachment` property: * true (treat this data element as an attachment to be uploaded) * false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. -**Note**: if the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element." +> __NOTE:__ +> If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element." ### Example Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. @@ -74,7 +78,8 @@ A client MAY send a request that contains attachments using the media type "mult ### Mulipart requests This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. -**Note**: At this time, multi-file attachements per template data object are not supported. +> __NOTE:__ +> At this time, multi-file attachements per template data object are not supported. ### Example Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. From ca93e81f85d0b050d4d0bd79d4cad28b1cf3a07f Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 21:47:31 -0700 Subject: [PATCH 46/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index d75af14..e101137 100644 --- a/attachment.md +++ b/attachment.md @@ -55,7 +55,7 @@ The two valid values for the `attachment` property: * false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. > __NOTE:__ -> If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element." +> If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. ### Example Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. From 09f24dc816243cc47fd4677df05d1b8a54848f40 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 21:48:54 -0700 Subject: [PATCH 47/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index e101137..867b5ae 100644 --- a/attachment.md +++ b/attachment.md @@ -73,7 +73,7 @@ Below you can can see the request contains a friend write template which specifi } ``` ## Sending attachments -A client MAY send a request that contains attachments using the media type "multipart/form-data". The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. +A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. From b06986033c8459b35c19fe9037ff6b41b89205c8 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 21:51:26 -0700 Subject: [PATCH 48/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 867b5ae..4550122 100644 --- a/attachment.md +++ b/attachment.md @@ -51,8 +51,8 @@ This extension defines a new property for the data object: `attachment`. This pr The two valid values for the `attachment` property: -* true (treat this data element as an attachment to be uploaded) -* false (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. +* `true` (treat this data element as an attachment to be uploaded) +* `false` (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. > __NOTE:__ > If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. From 82720a721dbe0ed653a575dada2e986bccbfe23a Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:04:55 -0700 Subject: [PATCH 49/67] Update attachment.md --- attachment.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 4550122..8fdd539 100644 --- a/attachment.md +++ b/attachment.md @@ -76,7 +76,16 @@ Below you can can see the request contains a friend write template which specifi A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests -This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for the guidelines. +This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for guidelines on the proper way to craft the request. + +A few key points to remember in the context of Collection-Json: + +* For each data object in the write template there SHOULD be: +** A seperate part for the data object. +** A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. +** If the template data object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. +** If the template data object has `"attachment":"true"` then the body SHOULD contain the file contents. +** If the template data object does not have `"attachment":"true"` then body SHOULD contain a value. > __NOTE:__ > At this time, multi-file attachements per template data object are not supported. From db250652cacb00f1c1051ced3acd37157953957c Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:06:09 -0700 Subject: [PATCH 50/67] Update attachment.md --- attachment.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/attachment.md b/attachment.md index 8fdd539..8ee7ea1 100644 --- a/attachment.md +++ b/attachment.md @@ -78,14 +78,14 @@ A client MAY send a request that contains attachments using the media type `mult ### Mulipart requests This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for guidelines on the proper way to craft the request. -A few key points to remember in the context of Collection-Json: +Some key points to remember in the context of Collection+JSON: * For each data object in the write template there SHOULD be: -** A seperate part for the data object. -** A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. -** If the template data object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. -** If the template data object has `"attachment":"true"` then the body SHOULD contain the file contents. -** If the template data object does not have `"attachment":"true"` then body SHOULD contain a value. + * A seperate part for the data object. + * A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. + * If the template data object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. + * If the template data object has `"attachment":"true"` then the body SHOULD contain the file contents. + * If the template data object does not have `"attachment":"true"` then body SHOULD contain a value. > __NOTE:__ > At this time, multi-file attachements per template data object are not supported. From e22accb1cf9532a12b72f282ad182e8d213eca5d Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:09:13 -0700 Subject: [PATCH 51/67] Update attachment.md --- attachment.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/attachment.md b/attachment.md index 8ee7ea1..0ecd223 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This extension outlines an extension which supports sending and receiving `collection+json` documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. +This extension supports sending and receiving `collection+json` documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). @@ -76,12 +76,12 @@ Below you can can see the request contains a friend write template which specifi A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests -This extension compiles with [RFC2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for guidelines on the proper way to craft the request. +This extension compiles with [RFC 2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for guidelines on the proper way to craft the request. Some key points to remember in the context of Collection+JSON: * For each data object in the write template there SHOULD be: - * A seperate part for the data object. + * A separate body part for the data object. * A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. * If the template data object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. * If the template data object has `"attachment":"true"` then the body SHOULD contain the file contents. @@ -109,7 +109,7 @@ content-type: image/jpeg ... --AaB03x ``` -## Receving attachments +## Receiving attachments A client MAY receive a response which contains links which represent downloadable attachments. ## Attachment render value From b74332d3e93180117efc698e110da252ea237e46 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:11:19 -0700 Subject: [PATCH 52/67] Update attachment.md --- attachment.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/attachment.md b/attachment.md index 0ecd223..86cdef2 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This extension supports sending and receiving `collection+json` documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. +This extension supports sending and receiving `Collection+JSON` (CJ) documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). @@ -23,13 +23,13 @@ To see a response containing attachment links, use the following command or just curl http://cj-attachment.azurewebsites.net/friends -v ``` -You can also grab a specific friend, using the href for the item in the payload. Also you can just as well create a direct request using the shortname (first initial + last name) +You can also grab a specific `friend`, using the `href` for the `item` in the payload. Also you can just as well create a direct request using the shortname (first initial + last name) ```test curl http://cj-attachment.azurewebsites.net/friends/mamundsen ``` -To send a multipart/form-data request with files, use the following command subsituting `thumbnail.png` with your own image. +To send a `multipart/form-data` request with files, use the following command subsituting `thumbnail.png` with your own image. ```text curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" --form blog="http://example.org/jdoe" --form avatar="@./thumbnail.png" http://cj-attachment.azurewebsites.net/friends @@ -38,10 +38,10 @@ curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. ## Write template -A client MAY receive a CollectionJson document containing a Write template which accepts attachments which the client can use to send files. +A client MAY receive a CJ document containing a Write template which accepts attachments which the client can use to send files. ### Content-type property -This extension defines a new optional property for the template object: `contentType`. The two valid values for `contentType ` are: +This extension defines a new optional property for the template object: `contentType`. The two valid values for `contentType` are: * `multipart/form-data` (this is the one to use for uploading attachments) * `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. From 96eddfc48ad792b25feac09dd5c56d1d0560c448 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:26:49 -0700 Subject: [PATCH 53/67] Update attachment.md --- attachment.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/attachment.md b/attachment.md index 86cdef2..e619149 100644 --- a/attachment.md +++ b/attachment.md @@ -1,5 +1,5 @@ # Attachment extension -This extension supports sending and receiving `Collection+JSON` (CJ) documents containing file attachments. This approach uses a multipart/form-data request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. +This extension supports sending and receiving `Collection+JSON` (CJ) documents containing file attachments. This approach uses a `multipart/form-data` request for sending attachments and annotated links in the response for surfacing attachments to be downloaded. Each of the examples below is based on the existing CJ friends [example](http://amundsen.com/media-types/collection/examples/). @@ -23,13 +23,13 @@ To see a response containing attachment links, use the following command or just curl http://cj-attachment.azurewebsites.net/friends -v ``` -You can also grab a specific `friend`, using the `href` for the `item` in the payload. Also you can just as well create a direct request using the shortname (first initial + last name) +You can also grab a specific `friend`, using the `href` for the `item` in the payload. Also you can just as well create a direct request using the short name (first initial + last name) ```test curl http://cj-attachment.azurewebsites.net/friends/mamundsen ``` -To send a `multipart/form-data` request with files, use the following command subsituting `thumbnail.png` with your own image. +To send a `multipart/form-data` request with files, use the following command substituting `thumbnail.png` with your own image. ```text curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" --form blog="http://example.org/jdoe" --form avatar="@./thumbnail.png" http://cj-attachment.azurewebsites.net/friends @@ -38,27 +38,27 @@ curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. ## Write template -A client MAY receive a CJ document containing a Write template which accepts attachments which the client can use to send files. +A client MAY receive a CJ document containing a `Write Template` that accepts attachments that the client can use to send files. ### Content-type property This extension defines a new optional property for the template object: `contentType`. The two valid values for `contentType` are: -* `multipart/form-data` (this is the one to use for uploading attachments) -* `application/vnd.collection+json` (this is the one to use for sending regular CJ documents) If the content-type property is missing, clients SHOULD use `application/vnd.collection+json` when sending a CJ document. If the content-type property is not supported and/or the provided value is not understood by the client, the client MUST use `application/vnd.collection+json` when sending CJ documents. +* `multipart/form-data` - This is the one to use for uploading attachments. +* `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. If the content-type property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ documents. ### Attachment property This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. The two valid values for the `attachment` property: -* `true` (treat this data element as an attachment to be uploaded) -* `false` (treat this data element as a text element) If the client does not support the `attachment` property and/or the value of this property is not understood, the client MUST treat the data element as a text element. +* `true`- Treat this data element as an attachment to be uploaded +* `false` - Treat this data element as a text element. If the client does not support the `attachment` property and/or the client does not understand the value of this property, the client MUST treat the data element as a text element. > __NOTE:__ > If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. ### Example -Below you can can see the request contains a friend write template which specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. +Below you can can see the request contains a friend `Write Template` that specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. ```javascript { @@ -88,10 +88,10 @@ Some key points to remember in the context of Collection+JSON: * If the template data object does not have `"attachment":"true"` then body SHOULD contain a value. > __NOTE:__ -> At this time, multi-file attachements per template data object are not supported. +> At this time, multi-file attachments per template `data` object are not supported. ### Example -Below you can can see the request contains three body parts. The first two contain textual information for full-name and email, while the third is an attachment containing the avatar. +Below you can see the request contains three body parts. The first two contain textual information for `full-name` and `email`, while the third is an attachment containing the `avatar` image. ``` content-type: multipart/form-data, boundary=AaB03x @@ -110,13 +110,13 @@ content-type: image/jpeg --AaB03x ``` ## Receiving attachments -A client MAY receive a response which contains links which represent downloadable attachments. +A client MAY receive a response that contains links that represent downloadable attachments. ## Attachment render value A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example -Below is an example of a response containing links which are attachments, namely the `avatar` link has a `render` value of `attachment`. The client in this casse SHOULD download the associated image. +Below is an example of a response containing links that are attachments, namely the `avatar` link has a `render` value of `attachment`. The client in this case SHOULD download the associated image. ``` content-type: application/vnd.collection+json From 154886b7564ae9cdafe71a94a98fc0f877be9cc2 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:32:04 -0700 Subject: [PATCH 54/67] Update attachment.md --- attachment.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/attachment.md b/attachment.md index e619149..33090af 100644 --- a/attachment.md +++ b/attachment.md @@ -38,10 +38,10 @@ curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. ## Write template -A client MAY receive a CJ document containing a `Write Template` that accepts attachments that the client can use to send files. +A client MAY receive a CJ document containing a _Write Template_ that accepts attachments that the client can use to send files. ### Content-type property -This extension defines a new optional property for the template object: `contentType`. The two valid values for `contentType` are: +This extension defines a new optional property for the `template` object: `contentType`. The two valid values for `contentType` are: * `multipart/form-data` - This is the one to use for uploading attachments. * `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. If the content-type property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ documents. @@ -58,7 +58,7 @@ The two valid values for the `attachment` property: > If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. ### Example -Below you can can see the request contains a friend `Write Template` that specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. +Below you can can see the request contains a friend _Write Template_ that specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. ```javascript { @@ -73,19 +73,19 @@ Below you can can see the request contains a friend `Write Template` that specif } ``` ## Sending attachments -A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the write template passed as form data via the `content-disposition header` as well as file uploads. +A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the _Write Template_ passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests This extension compiles with [RFC 2388] (http://tools.ietf.org/html/rfc2388) and [draft-multi-part-form-data] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05) for sending requests. You should refer to these documents for guidelines on the proper way to craft the request. Some key points to remember in the context of Collection+JSON: -* For each data object in the write template there SHOULD be: +* For each data object in the _Write Template_ there SHOULD be: * A separate body part for the data object. * A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. - * If the template data object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. - * If the template data object has `"attachment":"true"` then the body SHOULD contain the file contents. - * If the template data object does not have `"attachment":"true"` then body SHOULD contain a value. + * If the template `data` object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. + * If the template `data` object has `"attachment":"true"` then the body SHOULD contain the file contents. + * If the template `data` object does not have `"attachment":"true"` then body SHOULD contain a value. > __NOTE:__ > At this time, multi-file attachments per template `data` object are not supported. From f49e75a04c9dc25c07e448bdd3fd74317199d0e9 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:32:54 -0700 Subject: [PATCH 55/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 33090af..a35d3a8 100644 --- a/attachment.md +++ b/attachment.md @@ -118,7 +118,7 @@ A new `render` value of `attachment` is introduced for links. This informs the c ### Example Below is an example of a response containing links that are attachments, namely the `avatar` link has a `render` value of `attachment`. The client in this case SHOULD download the associated image. -``` +```javascript content-type: application/vnd.collection+json { "collection" : { From 9bb8c4b83928e40175923861c63a8bbf694a648a Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:33:47 -0700 Subject: [PATCH 56/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index a35d3a8..5d064c2 100644 --- a/attachment.md +++ b/attachment.md @@ -112,7 +112,7 @@ content-type: image/jpeg ## Receiving attachments A client MAY receive a response that contains links that represent downloadable attachments. -## Attachment render value +### Attachment render value A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example From 06868bbe3763f25405a7de7840a0b755ee2f2f44 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:36:58 -0700 Subject: [PATCH 57/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 5d064c2..57aec0c 100644 --- a/attachment.md +++ b/attachment.md @@ -37,7 +37,7 @@ curl -0 -v -include --form full-name="John Doe" --form email="jdoe@example.org" After the image is uploaded, you will find it at `http://cj-attachment.azurewebsites.net/avatars?name={file}` i.e. `http://cj-attachment.azurewebsites.net/avatars/name=thumbnail.png` in the previous case. You can open it in a browser and it will download. -## Write template +## Receiving Write Templates that accept attachments A client MAY receive a CJ document containing a _Write Template_ that accepts attachments that the client can use to send files. ### Content-type property From 6a79d1b51aab7d97904fd6bd052f6a390a8e77a1 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:37:50 -0700 Subject: [PATCH 58/67] Update attachment.md --- attachment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/attachment.md b/attachment.md index 57aec0c..8b580c2 100644 --- a/attachment.md +++ b/attachment.md @@ -72,7 +72,7 @@ Below you can can see the request contains a friend _Write Template_ that specif } } ``` -## Sending attachments +## Sending items with attachments A client MAY send a request that contains attachments using the media type `multipart/form-data`. The request contains the data for the _Write Template_ passed as form data via the `content-disposition header` as well as file uploads. ### Mulipart requests @@ -109,8 +109,8 @@ content-type: image/jpeg ... --AaB03x ``` -## Receiving attachments -A client MAY receive a response that contains links that represent downloadable attachments. +## Receiving items with attachments +A client MAY receive a response that contains `items` with links that represent downloadable attachments. ### Attachment render value A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. From 3a949cd26c4e1338462b6320f43ef5526bfdb01d Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:38:16 -0700 Subject: [PATCH 59/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 8b580c2..8c3d22f 100644 --- a/attachment.md +++ b/attachment.md @@ -109,7 +109,7 @@ content-type: image/jpeg ... --AaB03x ``` -## Receiving items with attachments +## Receiving items with attachment links A client MAY receive a response that contains `items` with links that represent downloadable attachments. ### Attachment render value From b87e14eeff1d1ce182ba2a73256ce808d2c22232 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 22:39:21 -0700 Subject: [PATCH 60/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 8c3d22f..110cb9b 100644 --- a/attachment.md +++ b/attachment.md @@ -110,7 +110,7 @@ content-type: image/jpeg --AaB03x ``` ## Receiving items with attachment links -A client MAY receive a response that contains `items` with links that represent downloadable attachments. +A client MAY receive a response that contains `items` with `link` objects that represent downloadable attachments. ### Attachment render value A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. From 4b2c6ac0d149dc41c4c629d006cd6e37f762abec Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 23:46:38 -0700 Subject: [PATCH 61/67] Update attachment.md --- attachment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 110cb9b..cdaa19d 100644 --- a/attachment.md +++ b/attachment.md @@ -40,11 +40,11 @@ After the image is uploaded, you will find it at `http://cj-attachment.azurewebs ## Receiving Write Templates that accept attachments A client MAY receive a CJ document containing a _Write Template_ that accepts attachments that the client can use to send files. -### Content-type property +### contentType property This extension defines a new optional property for the `template` object: `contentType`. The two valid values for `contentType` are: * `multipart/form-data` - This is the one to use for uploading attachments. -* `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. If the content-type property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ documents. +* `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. If the contentType property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ documents. ### Attachment property This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. From a39f626e43d02b08d080791878ae51d96ba7f4ef Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Wed, 15 Oct 2014 23:47:20 -0700 Subject: [PATCH 62/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index cdaa19d..1c5fd81 100644 --- a/attachment.md +++ b/attachment.md @@ -58,7 +58,7 @@ The two valid values for the `attachment` property: > If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. ### Example -Below you can can see the request contains a friend _Write Template_ that specifies a content-type of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. +Below you can can see the request contains a friend _Write Template_ that specifies a contentType of `multipart/form-data`. The `avatar` data object is marked as an attachment, indicating that a file should be uploaded. ```javascript { From b8179bb8feaf1ac4a5bf674512f05a726902ee55 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Thu, 16 Oct 2014 00:00:44 -0700 Subject: [PATCH 63/67] Update attachment.md --- attachment.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/attachment.md b/attachment.md index 1c5fd81..4587560 100644 --- a/attachment.md +++ b/attachment.md @@ -15,7 +15,6 @@ The following RFCs/documents form the basis of the approach in this document: > __NOTE:__ > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://tools.ietf.org/html/rfc2119). - ## Live example To see a response containing attachment links, use the following command or just open in a browser: @@ -44,9 +43,12 @@ A client MAY receive a CJ document containing a _Write Template_ that accepts at This extension defines a new optional property for the `template` object: `contentType`. The two valid values for `contentType` are: * `multipart/form-data` - This is the one to use for uploading attachments. -* `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. If the contentType property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ documents. +* `application/vnd.collection+json` - This is the one to use for sending regular CJ `items`. + +> __NOTE:__ +> If the `contentType` property is missing, not supported and/or the client does not understand the provided value, the client MUST use `application/vnd.collection+json` when sending CJ `items`. -### Attachment property +### attachment property This extension defines a new property for the data object: `attachment`. This property is only valid for data objects that are children of the template object. The two valid values for the `attachment` property: @@ -80,18 +82,18 @@ This extension compiles with [RFC 2388] (http://tools.ietf.org/html/rfc2388) and Some key points to remember in the context of Collection+JSON: -* For each data object in the _Write Template_ there SHOULD be: - * A separate body part for the data object. - * A `content-disposition` header of type `form-data` with a `name` parameter matching the template object name. +* For each `data object` in the _Write Template_ there SHOULD be: + * A separate [part] (https://tools.ietf.org/html/draft-ietf-appsawg-multipart-form-data-05#section-5) for the `data` object. + * A `content-disposition` header of type `form-data` with a `name` parameter matching the template `data` object` name. * If the template `data` object has `"attachment":"true"` then the `content-disposition` header MAY contain a `filename` parameter. * If the template `data` object has `"attachment":"true"` then the body SHOULD contain the file contents. - * If the template `data` object does not have `"attachment":"true"` then body SHOULD contain a value. + * If the template `data` object does not have `"attachment":"true"` then the body SHOULD contain a value. > __NOTE:__ -> At this time, multi-file attachments per template `data` object are not supported. +> At this time, multi-file attachents per template `data` object are not supported. ### Example -Below you can see the request contains three body parts. The first two contain textual information for `full-name` and `email`, while the third is an attachment containing the `avatar` image. +Below you can see the request contains three parts. The first two contain textual information for `full-name` and `email`, while the third is an attachment containing the `avatar` image. ``` content-type: multipart/form-data, boundary=AaB03x From 7446176b4e6de537411b89b9a8f290bc5713cde2 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Thu, 16 Oct 2014 00:02:16 -0700 Subject: [PATCH 64/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 4587560..076940e 100644 --- a/attachment.md +++ b/attachment.md @@ -90,7 +90,7 @@ Some key points to remember in the context of Collection+JSON: * If the template `data` object does not have `"attachment":"true"` then the body SHOULD contain a value. > __NOTE:__ -> At this time, multi-file attachents per template `data` object are not supported. +> At this time, multi-file attachments per template `data` object are not supported. ### Example Below you can see the request contains three parts. The first two contain textual information for `full-name` and `email`, while the third is an attachment containing the `avatar` image. From e054a5b1caef38265d60dcd5b34bacafe95069a9 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Thu, 16 Oct 2014 00:04:43 -0700 Subject: [PATCH 65/67] Update attachment.md --- attachment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/attachment.md b/attachment.md index 076940e..4ea0baa 100644 --- a/attachment.md +++ b/attachment.md @@ -5,7 +5,7 @@ Each of the examples below is based on the existing CJ friends [example](http:// It is inspired by this [discussion](https://groups.google.com/forum/#!topic/collectionjson/pzdkNGx-aPE) -The following RFCs/documents form the basis of the approach in this document: +The following RFCs/documents form the basis of the approach used by this extension: * [1341] (http://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) - The Multipart Content-Type * [2388] (http://tools.ietf.org/html/rfc2388) - Returning Values from Forms: multipart/form-data From 688db86b38aa3d1a8c4ec25d9c794621e7081201 Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Thu, 16 Oct 2014 00:07:30 -0700 Subject: [PATCH 66/67] Update attachment.md --- attachment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/attachment.md b/attachment.md index 4ea0baa..5bf893f 100644 --- a/attachment.md +++ b/attachment.md @@ -122,6 +122,7 @@ Below is an example of a response containing links that are attachments, namely ```javascript content-type: application/vnd.collection+json + { "collection" : { "version" : "1.0", From d233882f788b90ee8acee3c7f4c07a411a0beaff Mon Sep 17 00:00:00 2001 From: Glenn Block Date: Thu, 16 Oct 2014 00:09:47 -0700 Subject: [PATCH 67/67] Update attachment.md --- attachment.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/attachment.md b/attachment.md index 5bf893f..c0cd66c 100644 --- a/attachment.md +++ b/attachment.md @@ -54,7 +54,7 @@ This extension defines a new property for the data object: `attachment`. This pr The two valid values for the `attachment` property: * `true`- Treat this data element as an attachment to be uploaded -* `false` - Treat this data element as a text element. If the client does not support the `attachment` property and/or the client does not understand the value of this property, the client MUST treat the data element as a text element. +* `false` - Treat this data element as a text element. > __NOTE:__ > If the attachment property is missing or set to a value to client does not understand, the client SHOULD treat the data element as a text element. @@ -115,7 +115,10 @@ content-type: image/jpeg A client MAY receive a response that contains `items` with `link` objects that represent downloadable attachments. ### Attachment render value -A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. +A new `render` value of `attachment` is introduced for links. This informs the client that it should treat the `href` for the link as downloadable. + +> __NOTE:__ +> Clients that do not support the `attachment` value for render MUST treat the associated href as a navigation link. ### Example Below is an example of a response containing links that are attachments, namely the `avatar` link has a `render` value of `attachment`. The client in this case SHOULD download the associated image.