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.

Wir nutzen Cookies auf unserer Website. Einige von ihnen sind essenziell für den Betrieb der Seite, während andere uns helfen, diese Website und die Nutzererfahrung zu verbessern (Tracking Cookies). Sie können selbst entscheiden, ob Sie die Cookies zulassen möchten. Bitte beachten Sie, dass bei einer Ablehnung womöglich nicht mehr alle Funktionalitäten der Seite zur Verfügung stehen.