Drive Access Service API Documentation
This document describes the available endpoints, required parameters, and responses for the Drive Access Service API.
Note: Endpoints marked with [Authorize] require a valid JWT Bearer token in the
Authorization
header.
Table of Contents
- Authentication API
- Configuration API
- File Handle API
- File Operations API
- Version API
- Configuration Settings
Authentication API
POST /api/auth/login
Authenticates a user and returns a JWT token if the credentials are valid.
Request
- URL:
/api/auth/login
- Method:
POST
- Content-Type:
application/json
- Body:
{ "Username": "string", "Password": "string" }
Success Response
- Status Code: 200 OK
- Body:
{ "token": "string", "expires": "DateTime" }
Error Responses
- 400 Bad Request: When username or password is missing.
- 401 Unauthorized: When credentials are invalid.
Configuration API
GET /api/config
Retrieves configuration details.
Request
- URL:
/api/config
- Method:
GET
Success Response
- Status Code: 200 OK
- Body:
{ "Path": "string", "Description": "string", "TokenTimeoutMinutes": number, "FileHandleTimeoutMinutes": number }
File Handle API
[Authorize]
These endpoints manage file handles (open, write, read, seek, and close).
GET /api/filehandle/open
Opens a file stream and returns a file handle (GUID).
Request
- URL:
/api/filehandle/open
- Method:
GET
- Query Parameters:
path
(string, required): Relative file path.mode
(FileMode, required): File mode (e.g., Open, Create).
Security: Verifies that the provided path is within the allowed file system path.
Success Response
- Status Code: 200 OK
- Body:
{ "handle": "GUID" }
Error Response
- 401 Unauthorized: When the path is not within the allowed directory.
POST /api/filehandle/write
Writes data to an open file handle.
Request
- URL:
/api/filehandle/write
- Method:
POST
- Query Parameter:
handle
(GUID, required)
- Body: Raw binary data.
Success Response
- Status Code: 200 OK
Error Response
- 404 Not Found: When the file handle does not exist.
GET /api/filehandle/read
Reads data from an open file handle.
Request
- URL:
/api/filehandle/read
- Method:
GET
- Query Parameters:
handle
(GUID, required)numberOfBytes
(integer, optional): If zero or omitted, reads until end of file.
Success Response
- Status Code: 200 OK
- Headers:
X-BytesRead
: Number of bytes read.X-IsEndOfFile
: Boolean flag if end of file is reached.
- Body: Binary file content with
Content-Type: application/octet-stream
.
Error Response
- 404 Not Found: When the file handle does not exist.
POST /api/filehandle/seek
Sets the stream position of an open file handle.
Request
- URL:
/api/filehandle/seek
- Method:
POST
- Query Parameters:
handle
(GUID, required)position
(long, required): Position from the start of the file.
Success Response
- Status Code: 200 OK
- Body:
{ "position": number }
Error Response
- 404 Not Found: When the file handle does not exist.
GET /api/filehandle/close
Closes an open file handle.
Request
- URL:
/api/filehandle/close
- Method:
GET
- Query Parameter:
handle
(GUID, required)
Success Response
- Status Code: 200 OK
GET /api/filehandle/openhandles
Retrieves a list of all currently open file handles.
Request
- URL:
/api/filehandle/openhandles
- Method:
GET
Success Response
- Status Code: 200 OK
- Body:
{ "handles": [ "GUID", "GUID", "... (more GUIDs)" ] }
File Operations API
[Authorize]
These endpoints manage file and directory operations such as reading contents, creating/deleting directories, renaming, moving, uploading, and downloading files.
GET /api/fileoperations/readDirectory
Retrieves the contents of a directory.
Request
- URL:
/api/fileoperations/readDirectory
- Method:
GET
- Query Parameter:
path
(string, optional): Relative directory path (defaults to base path).
Security: Validates that the path is within the allowed file system path.
Success Response
- Status Code: 200 OK
- Body:
{ "files": [ { "Name": "string", "Directory": "string", "CreationTime": "DateTime", "LastAccessTime": "DateTime", "LastWriteTime": "DateTime", "Length": number } // ...more file objects ], "directories": [ { "Name": "string", "Directory": "string", "CreationTime": "DateTime", "LastAccessTime": "DateTime", "LastWriteTime": "DateTime" } // ...more directory objects ] }
Error Response
- 401 Unauthorized: When the path is not allowed.
POST /api/fileoperations/createDirectory
Creates a new directory.
Request
- URL:
/api/fileoperations/createDirectory
- Method:
POST
- Query Parameter:
path
(string, required): Relative directory path.
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "Directory created." }
Error Response
- 401 Unauthorized: When the path is not allowed.
DELETE /api/fileoperations/deleteDirectory
Deletes a directory.
Request
- URL:
/api/fileoperations/deleteDirectory
- Method:
DELETE
- Query Parameters:
path
(string, required): Relative directory path.recursive
(boolean, required): Delete subdirectories and files recursively.
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "Directory deleted." }
Error Response
- 401 Unauthorized: When the path is not allowed.
POST /api/fileoperations/isDirectoryEmpty
Checks if a directory is empty.
Request
- URL:
/api/fileoperations/isDirectoryEmpty
- Method:
POST
- Query Parameter:
path
(string, required): Relative directory path.
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "isEmpty": true, "message": "Directory is empty." // or "Directory is not empty." }
Error Responses
- 401 Unauthorized: When the path is not allowed.
- DirectoryNotFoundException: When the directory does not exist.
POST /api/fileoperations/rename
Renames a file or directory.
Request
- URL:
/api/fileoperations/rename
- Method:
POST
- Query Parameters:
oldName
(string, required): Current relative path.newName
(string, required): New name (without path).
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "File or directory renamed." }
Error Responses
- 401 Unauthorized: When the source path is not allowed.
- FileNotFoundException: When the source path does not exist.
GET /api/fileoperations/exists
Checks if a file or directory exists.
Request
- URL:
/api/fileoperations/exists
- Method:
GET
- Query Parameter:
path
(string, required): Relative path.
Success Response
- Status Code: 200 OK
- Body:
{ "exists": true }
Error Response
- 401 Unauthorized: When the path is not allowed.
DELETE /api/fileoperations/deleteFile
Deletes a file.
Request
- URL:
/api/fileoperations/deleteFile
- Method:
DELETE
- Query Parameter:
path
(string, required): Relative file path.
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "File deleted." }
Error Responses
- 401 Unauthorized: When the path is not allowed.
- FileNotFoundException: When the file does not exist.
POST /api/fileoperations/moveFile
Moves a file from a source path to a target path.
Request
- URL:
/api/fileoperations/moveFile
- Method:
POST
- Query Parameters:
sourcePath
(string, required): Current relative file path.targetPath
(string, required): New relative file path.
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "File moved successfully." }
Error Response
- 401 Unauthorized: When either the source or target path is not allowed.
POST /api/fileoperations/uploadFile
Uploads a file to a specified directory.
Request
- URL:
/api/fileoperations/uploadFile
- Method:
POST
- Content-Type:
multipart/form-data
- Form Data:
file
(IFormFile, required)path
(string, optional): Relative upload path (defaults to base path).
Success Response
- Status Code: 200 OK
- Body:
{ "status": "success", "message": "File uploaded successfully." }
Error Responses
- 401 Unauthorized: When the path is not allowed.
- 400 Bad Request: When the file is missing or empty.
GET /api/fileoperations/downloadFile
Downloads a file.
Request
- URL:
/api/fileoperations/downloadFile
- Method:
GET
- Query Parameter:
path
(string, required): Relative file path.
Success Response
- Status Code: 200 OK
- Headers: Appropriate download headers including
Content-Disposition
. - Body: File content with
Content-Type: application/octet-stream
.
Error Responses
- 401 Unauthorized: When the path is not allowed.
- FileNotFoundException: When the file does not exist.
Version API
GET /api/version
Returns the application name and version.
Request
- URL:
/api/version
- Method:
GET
Success Response
- Status Code: 200 OK
- Body:
{ "ApplicationName": "string", "Version": "string" }
Configuration Settings
Configuration values are read from the appsettings.json
file. Key settings include:
- JwtSettings:
Key
: Secret key used for signing JWT tokens.TimeoutMinutes
: Token expiration duration.Issuer
: Token issuer.Audience
: Token audience.
- Kestrel:
- HTTP/HTTPS endpoint configuration, including certificates and request size limits.
- Settings:
- Authentication: Contains username and password.
- FileSystem: Contains the base path and description.
FileHandleTimeoutMinutes
: Timeout for file handle inactivity.