Re: [camp] Issue 3: proposal direction with two choices

Hi Anish-

      

      Glad you updated CAMP-3 with this link.  Somehow I missed it first
      time round!  Obviously it raises a question about my draft
      proposal for CAMP-65...

      

      Q: What are the benefits of "pdpUri: cid:XXX" multi-part versus my
      suggestion of a single part and is it worth the overhead? *

      

      To attempt an answer I think it makes it easier for _javascript_ to
      upload as it won't have to build ZIPs on the fly.  That's pretty
      compelling.  But _requiring_ multipart from the client can also be
      tedious so my vote would be to require a platform to support
      EITHER a single part post which is interpreted as I described, or
      a multipart post where the first part is either the map containing
      { pdpUri: cid:XXX }, in YAML format (so allowing JSON), or
      possibly the pdp itself.  (I think I prefer the latter unless
      there is a good reason for the former?)

      

      Having the deployment plan also support cid: is nice as then
      artifacts could be part of the same multi-part.

      

      * = also have we settled on how we treat abbreviations in camel
      case?  i prefer pdpUri to pdpURI (otherwise you risk getting
      HTTPRESTAPI !)

      

      

      You also raised ... 

      

      Q:  multipart/form-data vs multipart/related

      

      I'm not sure.  Will have to investigate, but not now as I'll miss
      my flight!  :O

      You've probably chosen the right answer already of course.

      

      

      Best

      Alex

      

      

      On 01/05/2013 01:49, Anish Karmarkar wrote:

    

    
      
      Preamble
      I have had a long standing AI to provide a proposal for issue 3
      [1].

      

      In the past we have talked about (in this TC as well as in the
      collaboration) allowing clients to POST to the platform endpoint
      to upload a PDP. Subsequently, we have talked about allowing
      clients to include a PDP in their register request (see section
      6.11 in WD09 [2]).

      

      If we are going to allow clients to include PDP in their register
      request:

      1) we (the spec) would have a well-defined interoperable way to
      upload and register a PDP, and

      2) we can stay silent on how the platform does management of
      repositories/content. A platform can choose to allow someone to
      upload a PDP or manage a platform administered repository, allow
      for git push, partial updates etc -- this would be a platform
      specific extension. Given all the various ways a platform can
      manage this, best to stay silent.

      

      If you agree to the following, I would like to propose the
      following as a directional resolution for issue 3.

      Proposal (Directional)

      
      Section 6.11 currently allows one to POST a JSON message:

      {"pdp_uri" : "<uri-of-the-pdp>"}

      

      to the platform URI and get back a Location URI for the newly
      created AssemblyTemplate.

      

      This section would be modified to allow for the client to send a
      multipart MIME message, the root part of which would contain the
      same JSON message as before, but the URI would be a "cid:" uri
      [3]. This cid uri would point to another MIME part in the same
      POST message that contains the PDP. For example:

      

      

      MIME-Version: 1.0

        Content-Type: ... ;boundary=MIME_boundary;

        

        --MIME_boundary

        Content-Type: application/json

        Content-ID: <>

        

        {"pdp_uri" : "cid:"}

        

        --MIME_boundary

        Content-Type: application/zip

        Content-Transfer-Encoding: binary

        Content-ID: <>

        

        // binary octets for zip

        

        --MIME_boundary--

      

      

      The advantage of keeping the same root part as before (in section
      6.11) is: it will always be processed the same way. *Where* the
      PDP is located obviously changes, based on the URI scheme.
      Furthermore, if we decide to allow parametrization of register
      operations (which we should, but that is a different issue) then
      again the _expression_ and processing of those parameters remain the
      same regardless of whether the PDP is provided by value (in the
      POST request entity-body) or by reference (eg, a http URL).

      Open Issue
      What should the content-type of the multipart message be?

      There are two possible options: multipart/form-data [4] or
      multipart/related [5].

      1. multipart/form-data
      This is very HTML friendly and supported by most browsers. The
      CAMP platform can provide such an HTML. The message would look
      like this --

      

      MIME-Version: 1.0

        Content-Type: multipart/form-data; boundary=----MIME_boundary

        

        ------MIME_Boundary

        Content-Disposition: form-data; name="pdp_uri"

        

        cid:

        

        ------MIME_Boundary

        Content-Disposition: form-data; name="pdp"; filename="pdp.zip"

      Content-ID: <>

        Content-Type: application/zip

        

        //binary octet for zip

        

        ------MIME_Boundary
      
      

      

      If we decide to go with this, then it would make sense to use the
      media-type x-www-form-urlencoded for the case where the PDP is
      provided by reference (the current method in section 6.11). There
      are two disadvantages of this approach: (1) the POSTed root part
      is not JSON, and (2) if we allow for parametrization all the
      parameter would also not be JSON (or will be URL-encoded JSON).

      2. multipart/related
      This allows us to reuse existing serialization/representation for
      the root part as well as any parameters (if we decide to allow
      that). The message would like this --

      

      MIME-Version: 1.0

        Content-Type: multipart/related;boundary=MIME_boundary;

            type="application/json";

            start="<>";

        

        --MIME_boundary

        Content-Type: application/json

        Content-ID: <>

        

        {"pdp_uri" : "cid:"}

        

        --MIME_boundary

        Content-Type: application/zip

        Content-Transfer-Encoding: binary

        Content-ID: <>

        

        // binary octets for zip

        

        --MIME_boundary--

      

      I prefer multipart related. What do others think? Is there a more
      appropriate media-type to use?

      

      Furthermore, if we decide to go with this proposal, I would like
      to suggest that we add another optional, immutable attribute to
      the AssemblyTemplate: pdpURI. This would point to the URI from
      which the template was created. This would allow for things such
      as discovery, cloning, registering the same PDP multiple times
      (perhaps with different customization), and debugging.

      

      Thanks.

      

      -Anish

      --

      

      [1] https://tools.oasis-open.org/issues/browse/CAMP-3

      [2]
      https://www.oasis-open.org/apps/org/workgroup/camp/download.php/49008/camp-spec-v1.1-wd09.doc

      [3] http://www.ietf.org/rfc/rfc2392.txt

      [4] http://tools.ietf.org/html/rfc2388

      [5] http://tools.ietf.org/html/rfc2387