REST: mention FileRef encoding

[glebshalyganov]

In the section about downloading files, mention that in case when FileRef contains encoded parts(percent-encoded or containing + or &), it should be fully URL-encoded when passing as a query parameter. Just in case, fileRefs can always be passed in the URL-encoded format.

Also, in the section about uploading files, mention that name parameter should be URL-encoded if a file name contains spaces or reserved characters.

[mariodavid]

Hi @glebshalyganov ,

for the downloading part I would go ahead with the following description:

While for the uploading part, the situation seems to be a little more unclear. First I was wondering if you always have this capability on the multipart form. Normally I would expect that no-one writes this multipart form HTTP body manually. Secondly, there seems to be even a dedicated parameter for encoded filenames, called filename*. You can read more about it here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#as_a_header_for_a_multipart_body

filename*

The parameters filename and filename* differ only in that filename* uses the encoding defined in RFC 5987. When both filename and filename* are present in a single header field value, filename* is preferred over filename when both are understood.

Have you considered this mechanism as well?

[mariodavid]

for downloading, see: https://github.com/Haulmont/jmix-docs/pull/220

[glebshalyganov]

Hi @mariodavid

File upload controller supports multipart form and binary upload. Both methods support optional name parameter, where it is possible to explicitly specify a filename. In case of multipart form, the name parameter is indeed optional, because the filename can be taken from the file itself. In some cases name should be encoded. For example, when name contains +, the + should be encoded. Otherwise, it will be interpreted as an encoded space character on the server side and the resulting filename will not be the same as expected.

Secondly, there seems to be even a dedicated parameter for encoded filenames, called filename*. Have you considered this mechanism as well?

If i got it right, the filename here is a directive for the Content-Disposition header which is relevant for response. So it is not quite suitable for upload request.