mirror of
https://github.com/drakkan/sftpgo.git
synced 2024-11-21 23:20:24 +00:00
184b99d500
A structure similar to the one used for secrets would be better, but we don't want to break backwards compatibility. Also document that omitting the password field in the request body will preserve the current password when updating a user using the REST API. Added a test case for this. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
613 lines
No EOL
17 KiB
YAML
613 lines
No EOL
17 KiB
YAML
openapi: 3.0.3
|
|
tags:
|
|
- name: fs
|
|
info:
|
|
title: SFTPGo HTTPFs
|
|
description: |
|
|
SFTPGo can use custom storage backend implementations compliant with the API defined here.
|
|
HTTPFs is a work in progress and makes no API stability promises.
|
|
version: 0.1.0
|
|
license:
|
|
name: AGPL-3.0-only
|
|
url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
|
|
servers:
|
|
- url: /v1
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BasicAuth: []
|
|
paths:
|
|
/stat/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Describes the named object
|
|
operationId: stat
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/FileInfo'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/open/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: offset
|
|
in: query
|
|
description: 'offset, in bytes, from the start. If not specified 0 must be assumed'
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Opens the named file for reading
|
|
operationId: open
|
|
responses:
|
|
'200':
|
|
description: successful operation
|
|
content:
|
|
'*/*':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/create/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: flags
|
|
in: query
|
|
description: 'flags to use for opening the file, if omitted O_RDWR|O_CREATE|O_TRUNC must be assumed. Supported flags: https://pkg.go.dev/os#pkg-constants'
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
- name: checks
|
|
in: query
|
|
description: 'If set to `1`, the parent directory must exist before creating the file'
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
post:
|
|
tags:
|
|
- fs
|
|
summary: Creates or opens the named file for writing
|
|
operationId: create
|
|
requestBody:
|
|
content:
|
|
'*/*':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
required: true
|
|
responses:
|
|
201:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/rename/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: target
|
|
in: query
|
|
description: target name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
patch:
|
|
tags:
|
|
- fs
|
|
summary: Renames (moves) source to target
|
|
operationId: rename
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/remove/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
delete:
|
|
tags:
|
|
- fs
|
|
summary: Removes the named file or (empty) directory.
|
|
operationId: delete
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/mkdir/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
post:
|
|
tags:
|
|
- fs
|
|
summary: Creates a new directory with the specified name
|
|
operationId: mkdir
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/chmod/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: mode
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
patch:
|
|
tags:
|
|
- fs
|
|
summary: Changes the mode of the named file
|
|
operationId: chmod
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/chtimes/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: access_time
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: modification_time
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
patch:
|
|
tags:
|
|
- fs
|
|
summary: Changes the access and modification time of the named file
|
|
operationId: chtimes
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/truncate/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: size
|
|
in: query
|
|
required: true
|
|
description: 'new file size in bytes'
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
patch:
|
|
tags:
|
|
- fs
|
|
summary: Changes the size of the named file
|
|
operationId: truncate
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/OKResponse'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/readdir/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Reads the named directory and returns the contents
|
|
operationId: readdir
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FileInfo'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/dirsize/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Returns the number of files and the size for the named directory including any sub-directory
|
|
operationId: dirsize
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
files:
|
|
type: integer
|
|
description: 'Total number of files'
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
description: 'Total size of files'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/mimetype/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Returns the mime type for the named file
|
|
operationId: mimetype
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
mime:
|
|
type: string
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
/statvfs/{name}:
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: object name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
tags:
|
|
- fs
|
|
summary: Returns the VFS stats for the specified path
|
|
operationId: statvfs
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/StatVFS'
|
|
401:
|
|
$ref: '#/components/responses/Unauthorized'
|
|
403:
|
|
$ref: '#/components/responses/Forbidden'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/InternalServerError'
|
|
501:
|
|
$ref: '#/components/responses/NotImplemented'
|
|
default:
|
|
$ref: '#/components/responses/DefaultResponse'
|
|
components:
|
|
responses:
|
|
OKResponse:
|
|
description: successful operation
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
BadRequest:
|
|
description: Bad Request
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
Unauthorized:
|
|
description: Unauthorized
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
Forbidden:
|
|
description: Forbidden
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
NotFound:
|
|
description: Not Found
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
NotImplemented:
|
|
description: Not Implemented
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
Conflict:
|
|
description: Conflict
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
RequestEntityTooLarge:
|
|
description: Request Entity Too Large, max allowed size exceeded
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
InternalServerError:
|
|
description: Internal Server Error
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
DefaultResponse:
|
|
description: Unexpected Error
|
|
content:
|
|
application/json; charset=utf-8:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
schemas:
|
|
ApiResponse:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: 'message, can be empty'
|
|
error:
|
|
type: string
|
|
description: error description if any
|
|
FileInfo:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: base name of the file
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
description: length in bytes for regular files; system-dependent for others
|
|
mode:
|
|
type: integer
|
|
description: |
|
|
File mode and permission bits. More details here: https://golang.org/pkg/io/fs/#FileMode.
|
|
Let's see some examples:
|
|
- for a directory mode&2147483648 != 0
|
|
- for a symlink mode&134217728 != 0
|
|
- for a regular file mode&2401763328 == 0
|
|
last_modified:
|
|
type: string
|
|
format: date-time
|
|
StatVFS:
|
|
type: object
|
|
properties:
|
|
bsize:
|
|
type: integer
|
|
description: file system block size
|
|
frsize:
|
|
type: integer
|
|
description: fundamental fs block size
|
|
blocks:
|
|
type: integer
|
|
description: number of blocks
|
|
bfree:
|
|
type: integer
|
|
description: free blocks in file system
|
|
bavail:
|
|
type: integer
|
|
description: free blocks for non-root
|
|
files:
|
|
type: integer
|
|
description: total file inodes
|
|
ffree:
|
|
type: integer
|
|
description: free file inodes
|
|
favail:
|
|
type: integer
|
|
description: free file inodes for non-root
|
|
fsid:
|
|
type: integer
|
|
description: file system id
|
|
flag:
|
|
type: integer
|
|
description: bit mask of f_flag values
|
|
namemax:
|
|
type: integer
|
|
description: maximum filename length
|
|
securitySchemes:
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-KEY |