xkonti/file-api repository overview

⁠File API

A simple RESTful API that allows you to manipulate files and directories.

Examples and more info on GitHub: github.com/xkonti/file-api⁠

⁠Usage

⁠Running in Docker

The easiest way to run the File API is to use the Docker image. The image is available on Docker Hub⁠:

docker run -d -p 3210:3000 -e API_KEY=YOUR_API_KEY -v /your/directory/to/mount:/data xkonti/file-api:latest

Available configuration options:

• Internal port: 3000
• Mount point for the directory to be managed via API: /data
• API_KEY environment variable: the API key to use for authentication

⁠Authentication

An API key must be configured in order to use the API. The API key can be configured using the API_KEY environment variable. Please use something that is base64 encoded so that it can be used in HTTP headers and URL query.

Each HTTP request will be first checked for API key. If the API key is not provided, the request will be rejected with a 401 Unauthorized response. The API key can be provided in two ways:

⁠HTTP header: api-key

curl --request GET --url 'http://localhost:3000/list?path=%2F' --header 'apikey: YOUR_API_KEY'

⁠Query parameter: apikey

curl --request GET --url 'http://localhost:3000/list?path=%2F&apikey=YOUR_API_KEY'

⁠API

⁠List files and directories in a directory

You can list files and/or directories by using the /list endpoint with the following query parameters:

• path - the path of the directory to list (remember to encode it)
• dirs - whether to include directories or not (default: false). If directories are listed their contents will be nested.
• depth - how deep to list directories. The default 1 will list only files and directories within the specified directory - no contents of subdirectories will be listed.

⁠Download a file

You can download a specific file by using the /file endpoint with the following query parameters:

• path - the path of the file to download (remember to encode it)

If the file does not exist or a path is pointing to a directory, a 404 Not Found response will be returned.

⁠Upload a file

You can upload a specific file by using the POST /file endpoint with the following query parameters:

• path - the destination path of the file to upload (remember to url-encode it)
• overwrite - whether to overwrite the file if it already exists (default: false)

All the parent directories of the destination path will be created automatically if they do not exist.

The file contents should be sent in the request body in one of the following ways:

• multipart/form-data - the file contents should be sent as a file field
• application/octet-stream - the file contents should be sent as the request body

Possible responses:

• 201 - the file was uploaded successfully
• 400 - the request was malformed in some way:
  • the path parameter is missing
  • the path parameter is pointing to a directory
  • the file contents are missing
• 415 - unsupported content type
• 422 - unrecognized file contents format

⁠Check if file exists

You can check if a specific file exists by using the GET /file/exists endpoint with the following query parameters:

• path - the path of the file to check (remember to url-encode it)

Possible responses:

• 204 - the file exists
• 404 - the file does not exist
• 400 - the request was malformed in some way:
  • the path parameter is missing
  • the path parameter is pointing to a directory

⁠Get file size

You can get the size of a specific file by using the GET /file/size endpoint with the following query parameters:

• path - the path of the file to check (remember to url-encode it)

Possible responses:

• 200 - the file exists and the size is returned in the response body
• 404 - the file does not exist
• 400 - the request was malformed in some way:
  • the path parameter is missing
  • the path parameter is pointing to a directory

Response body with file size in bytes:

{
  "size": 123456
}