Files API

Overview

The file upload process essentially works as follows:

POST /files with the metadata to create a share. This will return an URL with the share you just created. (See List API.)
POST /files/<uuid>/content (the UUID is in the URL from the previous step) to upload the actual data of the share. (See Content API.)
GET /files/<uuid>/content to read the share.

Share modification is done with PUT /files/<uuid>/content.

Shares can be locked, which means they can’t be modified or deleted. See Lock API for more information.

Note

All data uploads are chunked: see Chunked upload protocol.

File Schema

In JSON, a file share has the following properties:

{
    "create_date": "2023-05-20T23:05:31.546561",
    "file_name": "file.txt",
    "initialized": true,
    "locked": false,
    "owner_name": "user",
    "share_id": "9ae90f06-a751-409c-a9fe-8277575b9914"
}

Property	Type	Limits	Description
`create_date`	Date	Time at which this share was created.	Read-only
`file_name`	String		The file’s name (with extension).
`initialized`	Boolean	Read-only	Shows if content exists for this share.
`locked`	Boolean	Read-only	Shows if share is locked (see Lock API.)
`owner_name`	string		Username of the owner.
`share_id`	string	Read-only	UUID that uniquely identifies this share.

Note

Share ownership can be changed by changing owner_name. Do note that setting it to null is equivalent to unauthenticated users owning the share.

Metadata API

The File Metadata API allows managing file shares’ metadata.

Sachet implements the following endpoints for this API:

GET /files/<file_uuid>
PATCH /files/<file_uuid>
PUT /files/<file_uuid>

GET

Requesting GET /files/<file_uuid> returns a JSON object conforming to the File schema. This contains the information about the share with the specified UUID.

An example response:

{
    "file_name": "file.txt",
    "initialized": true,
    "locked": false,
    "owner_name": "user",
    "share_id": "9ae90f06-a751-409c-a9fe-8277575b9914"
}

This method requires the read permission.

PATCH

Requesting PATCH /files/<file_uuid> allows modifying some or all fields of the share’s metadata. The request body is JSON conforming to the File schema. Properties may be left out: they won’t be modified.

For example, to modify a share’s filename:

{
    "file_name": "foobar.mp3"
}

This method requires the modify permission.

PUT

Requesting PUT /files/<file_uuid> completely replaces a share’s metadata. The request body is JSON conforming to the File schema. No property may be left out.

For example:

{
    "file_name": "foobar.mp4",
    "owner_name": "user"
}

Note

The permissions from the schema that are missing here are read-only.

List API

The File List API allows listing shares and creating new ones:

GET /files
POST /files

GET

GET /files is a paginated endpoint that returns a list of shares.

To access this endpoint, a user needs the list shares permission.

POST

POST /files creates a new share. The request body must conform to the File schema.

To access this endpoint, a user needs the create shares permission.

Note

The share created here is empty, and only contains metadata. See Content API for information on uploading content.

Upon success, the server will respond like this:

{
  "status": "success",
  "url": "/files/d9eafb5e-af48-40ec-b6fd-f7ea99e6d990"
}

The url field represents the share you just created. It can be used in further requests to upload content to the share.

Content API

The File Content API allows managing file shares’ contents.

Sachet implements the following endpoints for this API:

POST /files/<file_uuid>/content
PUT /files/<file_uuid>/content
GET /files/<file_uuid>/content

POST

POST /files/<file_uuid>/content initializes the content of an empty share. This endpoint requires the create shares permission.

Note

You must first create a share before initializing it: see List API for information about creation.

Uploads must be chunked (see Chunked upload protocol).

To modify the contents of an existing share, use PUT instead.

PUT

PUT /files/<file_uuid>/content modifies the content of an existing share. This endpoint requires the modify shares permission.

Note

You must initialize a share’s content using POST before modifying it.

Uploads must be chunked (see Chunked upload protocol).

GET

GET /files/<file_uuid>/content reads the contents of a share. This endpoint requires the read shares permission.

This endpoint supports HTTP Range headers.

Chunked upload protocol

To allow for uploading large files reliably, Sachet requires that you upload files in chunks.

Partial uploads do not affect the state of the share; a new file exists only once all chunks are uploaded.

Chunks are ordered by their index. Once an upload finishes, they are combined in that order to form the new file.

The server will respond with 200 OK when chunks are sent. When the final chunk is sent, and the upload is completed, the server will instead respond with 201 Created.

Every chunk has the following schema:

dztotalchunks = 3
dzchunkindex = 2
dzuuid = "unique_id"
upload = <binary data>

Note

This data is sent via a multipart/form-data request; it’s not JSON.

Property	Type	Description
`dztotalchunks`	Integer	Total number of chunks the client will send.
`dzchunkindex`	Integer	Number of the chunk being sent.
`dzuuid`	String	ID which is the same for all chunks in a single upload.
`upload`	Binary data (file)	Data contained in this chunk.

Lock API

Files can be locked and unlocked. When locked, a share can not be modified or deleted.

Note

When attempting illegal actions on a locked share, the server will respond 423 Locked.

The following API is used:

POST /files/<uuid>/lock
POST /files/<uuid>/unlock

A user needs the lock permission to access this API.

To query whether a file is locked or not, see Metadata API.