Files

Below API endpoints allow to upload and store files in ALX system.

Files technical design can be found in File uploads - Tech design

Permissions

Permission	Manageable via Roles	Description
store	false	Allows to store uploaded file in the public storage. Any authenticated user has it enabled.
list	false	Allows to list files in the public storage. Only Super Admin has it enabled.
delete	false	Allows to delete files in the public storage. Only Super Admin has it enabled.

Permissions for files can be checked by:

Context	Endpoint	Location	Available perms
Global scope	`GET /api/users/permissions/`	`files`	`store`, `list`, `delete`
Specific file	`GET /api/files/public-storage/`	`_meta.permissions`	`delete`

References

File uploads

POST /api/files/upload/

Uploads single file as temporary file to be used in other places in the ALX system. Unique token is returned in a response, to identify file on backend side. The token can be used for any compatible endpoint supporting uploaded files.

Permissions

Requires authentication.

Request

Body parameters

Request's body contains binary data of uploaded file.

Headers

Content-Disposition: attachment; filename=<filename>
Authorization: JWT access_token

Schema

json

POST /api/files/upload/

<binary data>

Validations

Allowed File Extensions

    csv,
    doc,
    docx,
    dot,
    gif,
    jfif,
    jpe,
    jpeg,
    jpg,
    json,
    odf,
    ods,
    odt,
    pdf,
    png,
    pot,
    potx,
    ppa,
    pps,
    ppsx,
    ppt,
    pptx,
    pwz,
    rdf,
    rtf,
    rtx,
    text,
    txt,
    wiz,
    wsdl,
    xla,
    xlb,
    xlc,
    xlm,
    xls,
    xlsx,
    xlt,
    xlw,
    xml,
    xpdl,
    xsl

Content-Disposition header:
- filename is required
Binary data:
- cannot be empty
- file extension should be allowed
- max size 50 MB

Response

Key	Type	Notes
token	string	Automatically generated by the backend.

Successful status 201 Created
Response body schema

json

{
  "token": <string>
}

Errors

Cause	Response code	Message
Binary data is empty	400 Bad Request	"detail": ["Empty content."]
Missing Content-Disposition header with filename	400 Bad Request	"detail": ["Missing filename. Request should include a Content-Disposition header with a filename parameter."]
Not allowed file extension	400 Bad Request	"detail": ["File extension “<extension>” is not allowed. Allowed extensions are: <allowed_extensions>."]
Size of file is too big	400 Bad Request	"detail": ["Max file size is 50.0 MB."]
Not authorized	401 Unauthorized
Timeout	504 Timeout

POST /api/files/public-storage/

Permanently saves uploaded files in storage without time limit.

Permissions

Requires authentication and files.store permission.

Request

Body parameters

Key	Type	Notes
token	string

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/files/public-storage/

{
  "token": <string>
}

Validations

token
- Max length: 36

Restrictions

Up to 10000 Public Files can be added, limit is configurable per build.

Response

Key	Type	Notes
uuid	uuid	Automatically generated by the backend.
filename	string	Name of a file without extension.
extension	string	File extension (contains dot), like ".jpg".
url	url	Link to file's content.
created_at	datetime
created_by	user
_meta.permissions	Object	Object describing permissions.

Successful status 201 Created
Response body schema

json

{
  "uuid": <uuid>,
  "filename": <string>,
  "extension": <string>,
  "url": <url>,
  "created_at": <datetime>,
  "created_by": <user>,
  "_meta": {
    "permissions": {
      "delete": <bool>
    }
  }
}

Errors

Cause	Response code	Message
"token" is missing	400 Bad Request	"token": ["This field is required."]
"token" is empty string	400 Bad Request	"token": ["This field may not be blank."]
"token" is null	400 Bad Request	"token": ["This field may not be null."]
"token" is not string	400 Bad Request	"token": ["Not a valid string."]
File with "token" does not exist	400 Bad Request	"token": ["Invalid token {token}."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

GET /api/files/public-storage/

Returns list of files from public storage.

Permissions

Requires authentication and files.list permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/files/public-storage/

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
uuid	uuid
filename	string	Name of a file without extension.
extension	string	File extension (contains dot), like ".jpg".
url	url	Link to file's content.
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema

json

{
  "limit": <int>,
  "offset": <int>,
  "filtered_count": <int>,
  "total_count": <int>,
  "next": <str>,
  "previous": <str>,
  "results": [
    {
      "uuid": <uuid>,
      "filename": <string>,
      "extension": <string>,
      "url": <url>,
      "created_at": <datetime>,
      "created_by": <user>,
      "_meta": {
        "permissions": {
            "delete": <bool>
        }
      }
    }
  ]
}

Sorting

Parameter	Example	Notes
filename	/api/files/public-storage/?ordering=filename	Ascending
filename	/api/files/public-storage/?ordering=-filename	Descending (-)
created_at	/api/files/public-storage/?ordering=created_at	Ascending
created_at	/api/files/public-storage/?ordering=-created_at	Descending (-)

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
filename	string
created_at	datetime
created_by	username

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"ordering": ["Select a valid choice. {value} is not one of the available choices."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

DELETE /api/files/public-storage/`uuid`/

Deletes single file from public storage.

Permissions

Requires authentication and files.delete permission.

Request

URL parameters

Key	Type	Notes
uuid	uuid

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

DELETE /api/files/public-storage/`uuid`/

Response

Successful status 204 No Content

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
File with "uuid" does not exist	404 Not Found	"detail": "Not found."

OPTIONS /api/files/public-storage/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/files/public-storage/

Response

Successful status 200 OK
Response body:

json

{
  "list": {
    "columns": [
      {
        "alias": "uuid",
        "type": "uuid",
        "predicates": [],
        "sort_ok": false
      },     
      {
        "alias": "filename",
        "type": "string",
        "predicates": [
          "exact",
          "iexact",
          "contains",
          "icontains",
          "startswith",
          "istartswith",
          "endswith",
          "iendswith"
        ],
        "sort_ok": true
      },
      {
        "alias": "extension",
        "type": "string",
        "predicates": [],
        "sort_ok": false
      },
      {
        "alias": "url",
        "type": "url",
        "predicates": [],
        "sort_ok": false
      },
      {
        "alias": "created_at",
        "type": "datetime",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "created_by",
        "type": "user",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": false,
        "autocomplete": "/api/users/autocomplete/?text__icontains="
      }
    ]
  },
  "details": {
    "schema": [
      {
        "alias": "token",
        "type": "string",
        "required": true,
        "validators": [
          {
            "type": "max_length",
            "length": 36
          }
        ]
      }
    ]
  },
  "restrictions": {
    "limit_items": 10000
  }
}

GET /api/files/public-storage/`uuid`/

Download file from public storage.

Permissions

No requires any authentication (is public).

Request

Headers

Content-Type: application/force-download

Schema

json

GET /api/files/public-storage/4fef1510-7b0b-46fd-84d4-7b933d3b6f72/

GET /api/files/response/file/`uuid`/

Download file from task response attachment.

Permissions

Requires authentication and task.view permission. For task related to given file.

Request

Headers

Content-Type: application/force-download

Schema

json

GET /api/files/response/file/4fef1510-7b0b-46fd-84d4-7b933d3b6f72/

GET /api/object-records/`record_id`/files/`uuid`/

Download file from object record document field.

Permissions

Requires authentication and object-records.view permission. For object record related to given file.

Request

Headers

Content-Type: application/force-download

Schema

json

GET /api/object-records/3/files/4fef1510-7b0b-46fd-84d4-7b933d3b6f72/

Files ​

Permissions ​

References ​

POST /api/files/upload/ ​

Permissions ​

Request ​

Validations ​

Allowed File Extensions ​

Response ​

Errors ​

POST /api/files/public-storage/ ​

Permissions ​

Request ​

Validations ​

Restrictions ​

Response ​

Errors ​

GET /api/files/public-storage/ ​

Permissions ​

Request ​

Response ​

Response results array ​

Sorting ​

Filtering ​

Errors ​

DELETE /api/files/public-storage/uuid/ ​

Permissions ​

Request ​

Response ​

Errors ​

OPTIONS /api/files/public-storage/ ​

Permissions ​

Request ​

Response ​

GET /api/files/public-storage/uuid/ ​

Permissions ​

Request ​

GET /api/files/response/file/uuid/ ​

Permissions ​

Request ​

GET /api/object-records/record_id/files/uuid/ ​

Permissions ​

Request ​

Files

Permissions

References

POST /api/files/upload/

Permissions

Request

Validations

Allowed File Extensions

Response

Errors

POST /api/files/public-storage/

Permissions

Request

Validations

Restrictions

Response

Errors

GET /api/files/public-storage/

Permissions

Request

Response

Response `results` array

Sorting

Filtering

Errors

DELETE /api/files/public-storage/`uuid`/

Permissions

Request

Response

Errors

OPTIONS /api/files/public-storage/

Permissions

Request

Response

GET /api/files/public-storage/`uuid`/

Permissions

Request

GET /api/files/response/file/`uuid`/

Permissions

Request

GET /api/object-records/`record_id`/files/`uuid`/

Permissions

Request