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.