Attached file, property type 'list of attachments' (using class 'abc/mnesia' and property 'patts' as an example)

Overview

Allows attaching an arbitrary number of file attachments to an entity with placement on disk in a preconfigured storage associated with the class collection.
And subsequently performing operations of reading, replacing, and deleting the attachment.

Each property of type `list of attachments` forms a separate endpoint of this type in the REST API. This is an `attachment` type field with the `multi`=`true` flag set.

A file uploaded with the POST method retains its name and extension, while when uploaded with the PUT method it acquires a name and extension identical to the specified attachment identifier (the last part of the path in the endpoint URL).

Uploading several files at once to a directory (field name) in `multipart/form-data` mode with a single POST request is allowed. Real names are taken from Content-Disposition headers and saved in metadata (JSON). It is also allowed to upload individual files directly to a specific directory element endpoint using Content-Type: application/octet-stream or multipart/form-data, from which only the first element will be taken. Similarly, the original file name is taken from the Content-Disposition header and saved in metadata.

The real path to attachments is formed the same way regardless of storage type:
* For categories - `…​/Domain/ClassName/Id12/Id34/Id56/IdRest/PropertyName/FileName`
* For history - `…​/Domain/ClassName/PartitionFieldDate/Id12/Id34/Id56/IdRest/PropertyName/FileName`

Requests

HTTP verb Endpoint Description

GET

/rest/v1/model/<classname>/<id>/<attachment_property>

Getting metadata for all attachment files associated with the property

GET

/rest/v1/model/<classname>/<id>/<attachment_property>/<file>

Downloading a specific attachment file

PUT

/rest/v1/model/<classname>/<id>/<attachment_property>/<file>

Uploading an attachment file

DELETE

/rest/v1/model/<classname>/<id>/<attachment_property>/<file>

Deleting an attachment file


Uploading attachment files preserving names

Upload to the collection is performed with Content-Type: multipart/formdata.

The request may contain one or several files. Files are placed under the names specified in the Content-Disposition headers of each part.

If a file with the specified name already exists, it is not saved and an error is returned. Depending on the Content-Type and the presence of successfully placed files, either a failed HTTP response or failure information in the body of a 200 OK HTTP response may be returned.

Request

Example request
POST /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="filename"; filename="app.mp3"
Content-Transfer-Encoding: binary

BINARY BODY OF 'app.mp3'
-----------boundary_69df8120352a996e--

Response

Example response
[
  {
    "name": "F.zip",
    "size": 8411,
    "last_modified": "2019-09-20 10:45:41"
  },
  {
    "name": "Package.bin",
    "size": 12268,
    "last_modified": "2019-09-20 10:45:49"
  }
]

Getting metadata for all attachment files associated with the property

Request

Example request
GET /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts HTTP/1.1

Response

The time in the last_modified field is returned in UTC.

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "name": "F.zip",
    "size": 8411,
    "last_modified": "2019-09-20 10:45:41"
  },
  {
    "name": "Package.bin",
    "size": 12268,
    "last_modified": "2019-09-20 10:45:49"
  }
]

Downloading a specific attachment file

Request

Table 1. Request parameters
Name Type Description

attachment

bool

Output type. Default false.

true – returned with the header Content-Disposition: attachment; filename=filename.ext or Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, where file.ext is the file name in UTF-8 encoding and URL-encoded.

false – returned without the Content-Disposition header.

Example request
GET /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3 HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/octet-stream; charset=utf-8
Content-Disposition: attachment; filename*=UTF-8''Some%20file.mp3

BINARY BODY OF 'Some file.mp3'

Uploading an attachment file

Replaces the file.

A single file is uploaded either with Content-Type: multipart/formdata or with an arbitrary non-multipart Content-Type.

If the upload uses Content-Type: multipart/formdata, only the first file is saved (the first part having a filename field in the Content-Disposition header), and the file name itself is ignored.

Request

Example request (octet-stream)
PUT /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3 HTTP/1.1
Content-Type: application/octet-stream

BINARY BODY OF 'app.mp3'
Example request (multipart)
PUT /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3 HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="abcde"; filename="app.mp3"
Content-Transfer-Encoding: binary

BINARY BODY OF 'app.mp3'
-----------boundary_69df8120352a996e--

Response

Example response
HTTP/1.1 204 No Content

Deleting an attachment file

Request

Example request
DELETE /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3 HTTP/1.1

Response

Example response
HTTP/1.1 204 No Content