Skip to content

api.md

Latest commit

 

History

History
446 lines (341 loc) · 10 KB

api.md

File metadata and controls

446 lines (341 loc) · 10 KB
Raw

📡 Remote FS API Documentation

This document provides a comprehensive guide to the Remote FS REST API endpoints, including authentication, request/response formats, and usage examples.

🔐 Authentication

All API requests require HMAC-SHA256 authentication using the X-signature header.

# Example signature calculation (pseudocode)
timestamp = current_unix_timestamp
data = method + path + query_params + timestamp
signature = hmac_sha256(secret_key, data)
auth_payload = {
    "timestamp": timestamp,
    "signature": signature
}
X-signature: base64_encode(json_encode(auth_payload))

Headers Required:

  • X-signature: Base64-encoded JSON containing timestamp and HMAC signature
  • Content-Type: application/json (for JSON payloads) or application/octet-stream (for file uploads)

🏥 Health Check

0. Health Check

Check if the API server is running and responsive.

Endpoint: GET /api/health

Authentication: Not required (public endpoint)

Response:

{
  "status": "ok",
  "timestamp": "2025-08-23T10:00:00.000Z"
}
# Example
curl https://server:443/api/health

📁 File System Operations

1. Lookup File/Directory

Get file or directory information by path.

Endpoint: GET /api/lookup/{path}

Parameters:

  • path (string, path parameter): Relative path to the file/directory (no leading slash)

Response: FileFormat object

# Examples
curl -H "X-signature: <auth>" https://server:443/api/lookup/folder/file.txt
curl -H "X-signature: <auth>" https://server:443/api/lookup/documents
curl -H "X-signature: <auth>" https://server:443/api/lookup/  # Root directory (empty path)

2. Get File Attributes by Inode

Get file attributes using the inode number.

Endpoint: GET /api/attributes/{ino}

Parameters:

  • ino (integer, path parameter): Inode number

Response: FileFormat object

# Example
curl -H "X-signature: <auth>" https://server:443/api/attributes/12345

3. Set File Attributes

Update file attributes by inode.

Endpoint: PUT /api/attributes/{ino}

Parameters:

  • ino (integer, path parameter): Inode number

Request Body: FileSetAttr object

{
  "ino": 12345,
  "mode": 644,
  "uid": 1000,
  "gid": 1000,
  "size": 1024,
  "atime": "2025-08-23T10:00:00.000Z",
  "mtime": "2025-08-23T10:00:00.000Z",
  "ctime": "2025-08-23T10:00:00.000Z",
  "flags": 0
}

Response: Updated FileFormat object

4. Get Path from Inode

Retrieve the full path for a given inode.

Endpoint: GET /api/path/{ino}

Parameters:

  • ino (integer, path parameter): Inode number

Response:

{
  "path": "documents/subfolder/file.txt"
}

5. List Directory Contents

List all files and subdirectories in a directory.

Endpoint: GET /api/list/{path}

Parameters:

  • path (string, path parameter): Relative path to directory (no leading slash)

Response: Array of FileFormat objects

# Examples
curl -H "X-signature: <auth>" https://server:443/api/list/documents
curl -H "X-signature: <auth>" https://server:443/api/list/  # Root directory (empty path)
curl -H "X-signature: <auth>" https://server:443/api/list/folder/subfolder

📄 File Content Operations

6. Read File Content

Read file content with optional offset and size parameters.

Endpoint: GET /api/files/{path}

Parameters:

  • path (string, path parameter): Relative path to file (no leading slash)
  • size (integer, query parameter, optional): Number of bytes to read
  • offset (integer, query parameter, optional): Starting offset in bytes

Response: File content as binary stream

# Examples
curl -H "X-signature: <auth>" https://server:443/api/files/document.txt
curl -H "X-signature: <auth>" "https://server:443/api/files/folder/large-file.bin?size=1024&offset=512"
curl -H "X-signature: <auth>" https://server:443/api/files/docs/readme.md

7. Write File Content

Write or update file content with streaming support.

Endpoint: PUT /api/files/{path}

Parameters:

  • path (string, path parameter): Relative path to file (no leading slash)
  • offset (integer, query parameter, optional): Starting offset for write operation
  • flags (integer, query parameter, optional): Write flags
  • write_flags (integer, query parameter, optional): Additional write flags

Request Body: Binary file content (application/octet-stream)

Response: Updated FileFormat object

# Example
curl -X PUT \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @local-file.txt \
  "https://server:443/api/files/documents/remote-file.txt?offset=0&flags=0&write_flags=0"

8. Create File

Create a new file with specified attributes.

Endpoint: POST /api/files

Request Body: FileCreationAttr object

{
  "parent_ino": 1,
  "name": "new-file.txt",
  "mode": 644,
  "umask": 22,
  "flags": 0,
  "uid": 1000,
  "gid": 1000,
  "owner": "user",
  "group": "users"
}

Response: Created FileFormat object (HTTP 201)

9. Delete File

Delete a file by path.

Endpoint: DELETE /api/files/{path}

Parameters:

  • path (string, path parameter): Relative path to file (no leading slash)

Response: Empty (HTTP 204 No Content)

# Example
curl -X DELETE -H "X-signature: <auth>" https://server:443/api/files/documents/unwanted-file.txt

10. Rename File/Directory

Rename or move a file or directory.

Endpoint: PUT /api/rename/files

Request Body: FileRenameAttr object

{
  "old_path": "documents/old-name.txt",
  "new_path": "documents/new-name.txt"
}

Response: Updated FileFormat object

📂 Directory Operations

11. Create Directory

Create a new directory with specified attributes.

Endpoint: POST /api/mkdir/{path}

Parameters:

  • path (string, path parameter): Relative path for new directory (no leading slash)

Request Body: FileCreationAttr object

{
  "parent_ino": 1,
  "name": "new-directory",
  "mode": 755,
  "umask": 22,
  "flags": 0,
  "uid": 1000,
  "gid": 1000,
  "owner": "user",
  "group": "users"
}

Response: Created directory FileFormat object (HTTP 201)

💾 Volume Information

12. Get Volume Statistics

Get filesystem volume information and statistics.

Endpoint: GET /api/volume/statfs

Response: VolumeInfo object

{
  "name": "remote_fs_volume",
  "total_space": 2000000000,
  "used_space": 500000000,
  "free_space": 1500000000,
  "block_size": 4096
}

📋 Data Types

FileFormat

{
  "ino": 12345,
  "name": "example.txt",
  "path": "documents/example.txt",
  "size": 1024,
  "parent_ino": 1,
  "modified": "2025-08-23T10:00:00.000Z",
  "file_type": "REGULARFILE",
  "permissions": "644",
  "owner": "user",
  "group": "users",
  "nlink": 1,
  "uid": 1000,
  "gid": 1000,
  "atime": 1692792000,
  "mtime": 1692792000,
  "ctime": 1692792000,
  "mode": 33188,
  "rdev": 0,
  "blksize": 4096,
  "blocks": 2
}

FileCreationAttr

{
  "parent_ino": 1,
  "name": "filename.txt",
  "mode": 644,
  "umask": 22,
  "flags": 0,
  "uid": 1000,
  "gid": 1000,
  "owner": "username",
  "group": "groupname"
}

FileSetAttr

{
  "ino": 12345,
  "mode": 644,
  "uid": 1000,
  "gid": 1000,
  "size": 2048,
  "atime": "2025-08-23T10:00:00.000Z",
  "mtime": "2025-08-23T10:00:00.000Z",
  "ctime": "2025-08-23T10:00:00.000Z",
  "flags": 0
}

FileRenameAttr

{
  "old_path": "documents/old-name.txt",
  "new_path": "archive/new-name.txt"
}

VolumeInfo

{
  "name": "remote_fs_volume",
  "total_space": 2000000000,
  "used_space": 500000000,
  "free_space": 1500000000,
  "block_size": 4096
}

⚠️ Error Responses

All endpoints return standardized error responses:

{
  "error_code": "METADATA_NOT_FOUND",
  "message": "File not found",
  "status": 404
}

Common Error Codes:

  • METADATA_NOT_FOUND: File or directory not found (404)
  • GENERIC_ERROR: General server error (500)
  • INVALID_PATH: Invalid path format (400)
  • PERMISSION_DENIED: Insufficient permissions (403)
  • FILE_EXISTS: File already exists (409)

🔗 Client Integration

The API is designed to work with the Remote FS client, which handles:

  • Automatic HMAC authentication
  • Binary streaming for large files
  • Caching strategies (TTL, LRU, Both, Disabled)
  • Cross-platform filesystem mounting (WinFsp/FUSE)

🎯 Usage Examples

Complete File Upload Workflow

# 1. Create file metadata
curl -X POST \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/json" \
  -d '{"parent_ino":1,"name":"upload.txt","mode":644,"umask":22,"flags":0,"uid":1000,"gid":1000,"owner":"user","group":"users"}' \
  https://server:443/api/files

# 2. Write file content
curl -X PUT \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @local-file.txt \
  https://server:443/api/files/upload.txt

# 3. Verify file was created
curl -H "X-signature: <auth>" https://server:443/api/lookup/upload.txt

Directory Operations

# 1. Create directory
curl -X POST \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/json" \
  -d '{"parent_ino":1,"name":"docs","mode":755,"umask":22,"flags":0,"uid":1000,"gid":1000,"owner":"user","group":"users"}' \
  https://server:443/api/mkdir/docs

# 2. List directory contents
curl -H "X-signature: <auth>" https://server:443/api/list/docs

# 3. Create file in directory
curl -X POST \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/json" \
  -d '{"parent_ino":2,"name":"readme.md","mode":644,"umask":22,"flags":0,"uid":1000,"gid":1000,"owner":"user","group":"users"}' \
  https://server:443/api/files

# 4. Write content to file in directory
curl -X PUT \
  -H "X-signature: <auth>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @readme.md \
  https://server:443/api/files/docs/readme.md