Implement File API about plone.restapi

[davisagli]

data/download as a URI or embedded base64 data? The former is probably better (fewer bytes to download)

[tisto]

As URI. We might want to support embedded base64 data in future versions (maybe with framing).

[lukasgraf]

The current serialization for a File looks like this:

{
  "@id": "http://nohost/plone/document.pdf",
  "@type": "File",
  "title": "My PDF document",
  "UID": "abef59538b3749debad950c3c5d35224",
  "...": "...",
  "file": "http://nohost/plone/document.pdf/@@download/file"
}

So a Named[Blob]File field gets serialized directly to its regular Plone download URL (as currently documented in the Serialization chapter).

I would propose to change the serialization to something that is slightly more in line with the format used for deserialization (upload):

{
  "@id": "http://nohost/plone/document.pdf",
  "...": "...",
  "file": {
    "filename": "document.pdf",
    "content-type": "application/pdf",
    "size": 65536,
    "download": "http://nohost/plone/document.pdf/@@download/file"
  }
}

That way, clients would have the necessary information to render a decent download link, including icon, filename and size without doing a second request.

The contract would then be that the client can do a GET request to the URL specified in download, with the same credentials, and will get back a response with appropriate Content-Disposition, Content-Length, and Content-Type headers as indicated in the metadata.

The same principle could probably be applied to images scales.

/cc @tisto @buchi

[tisto]

@lukasgraf you proposal looks good to me. It is essential that serialization/deserialization use the same structure. I guess from a HTTP spec perspective it would be correct if the client would send a GET request to "http://localhost:8080/Plone/document.pdf/@@download/file" with Accept "application/pdf" header. Though, since it works without the Accept header in Plone as well I guess we don't have to be pedantic about it.

[lukasgraf]

@tisto I agree, this would be the proper behavior. But since Accept: */* or no Accept header at all would also happen to work, we might just phrase this as a recommendation to the client / description of how the server is expected to behave in the docs.

I'll start working on this (and Images) then, PR coming up.

[tisto]

Closed by #115