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

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.