beenull/sftpgo-mirror
1
0
Fork 0
mirror of https://github.com/drakkan/sftpgo.git synced 2024-11-25 00:50:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sftpgo-mirror/httpd/schema/openapi.yaml

691 lines
20 KiB
YAML
Raw Normal View History

first version
2019-07-20 10:26:52 +00:00
openapi: 3.0.1
info:
title: SFTPGo
description: 'SFTPGo REST API'
version: 1.0.0
servers:
- url: /api/v1
paths:
add version info
2019-08-08 08:01:33 +00:00
/version:
get:
tags:
- version
summary: Get version details
operationId: get_version
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/VersionInfo'
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
/connection:
first version
2019-07-20 10:26:52 +00:00
get:
tags:
- connections
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
summary: Get the active users and info about their uploads/downloads
operationId: get_connections
first version
2019-07-20 10:26:52 +00:00
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/ConnectionStatus'
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
/connection/{connectionID}:
first version
2019-07-20 10:26:52 +00:00
delete:
tags:
- connections
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
summary: Terminate an active connection
operationId: close_connection
first version
2019-07-20 10:26:52 +00:00
parameters:
- name: connectionID
in: path
description: ID of the connection to close
required: true
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 200
message: "Connection closed"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/quota_scan:
get:
tags:
- quota
summary: Get the active quota scans
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
operationId: get_quota_scans
first version
2019-07-20 10:26:52 +00:00
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/QuotaScan'
post:
tags:
- quota
summary: start a new quota scan
description: A quota scan update the number of files and their total size for the given user
operationId: start_quota_scan
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
201:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 201
message: "Scan started"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
409:
description: Another scan is already in progress for this user
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 409
message: "Another scan is already in progress"
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/user:
get:
tags:
- users
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
summary: Returns an array with one or more users
add a basic web interface The builtin web interface allows to manage users and connections
2019-10-07 16:19:01 +00:00
description: For security reasons hashed passwords are omitted in the response
first version
2019-07-20 10:26:52 +00:00
operationId: get_users
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: The maximum number of items to return. Max value is 500, default is 100
- in: query
name: order
required: false
description: Ordering users by username
schema:
type: string
enum:
- ASC
- DESC
example: ASC
- in: query
name: username
required: false
description: Filter by username, extact match case sensitive
schema:
type: string
responses:
200:
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
post:
tags:
- users
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
summary: Adds a new SFTP/SCP user
first version
2019-07-20 10:26:52 +00:00
operationId: add_user
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
/user/{userID}:
get:
tags:
- users
summary: Find user by ID
add a basic web interface The builtin web interface allows to manage users and connections
2019-10-07 16:19:01 +00:00
description: For security reasons the hashed password is omitted in the response
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
operationId: get_user_by_id
first version
2019-07-20 10:26:52 +00:00
parameters:
- name: userID
in: path
description: ID of the user to retrieve
required: true
schema:
type: integer
format: int32
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/User'
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
put:
tags:
- users
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
summary: Update an existing user
operationId: update_user
first version
2019-07-20 10:26:52 +00:00
parameters:
- name: userID
in: path
description: ID of the user to update
required: true
schema:
type: integer
format: int32
requestBody:
required: true
content:
application/json:
schema:
$ref : '#/components/schemas/User'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
example:
status: 200
message: "User updated"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
delete:
tags:
- users
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
summary: Delete an existing user
operationId: delete_user
first version
2019-07-20 10:26:52 +00:00
parameters:
- name: userID
in: path
description: ID of the user to delete
required: true
schema:
type: integer
format: int32
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref : '#/components/schemas/ApiResponse'
example:
status: 200
message: "User deleted"
error: ""
400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 400
message: ""
error: "Error description if any"
403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 403
message: ""
error: "Error description if any"
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 404
message: ""
error: "Error description if any"
500:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
status: 500
message: ""
error: "Error description if any"
components:
schemas:
Permission:
type: string
enum:
- '*'
- list
- download
- upload
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 06:53:45 +00:00
- overwrite
first version
2019-07-20 10:26:52 +00:00
- delete
- rename
- create_dirs
- create_symlinks
description: >
Permissions:
set version to 0.9.2
2019-09-18 20:19:34 +00:00
* `*` - all permissions are granted
first version
2019-07-20 10:26:52 +00:00
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 06:53:45 +00:00
* `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite
first version
2019-07-20 10:26:52 +00:00
* `delete` - delete files or directories is allowed
* `rename` - rename files or directories is allowed
* `create_dirs` - create directories is allowed
* `create_symlinks` - create links is allowed
User:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
username:
type: string
password:
type: string
nullable: true
scp: add test case and document remote to remote transfers
2019-08-25 11:51:54 +00:00
description: password or public key are mandatory. If the password has no known hashing algo prefix it will be stored using argon2id. You can send a password hashed as bcrypt or pbkdf2 and it will be stored as is. For security reasons this field is omitted when you search/get users
rename public_key in public_keys remove compatibility layer to convert public keys newline delimited in json list
2019-08-07 21:41:10 +00:00
public_keys:
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
type: array
items:
type: string
first version
2019-07-20 10:26:52 +00:00
nullable: true
unhide public keys hiding public keys give no security improvement
2019-10-03 13:29:54 +00:00
description: a password or at least one public key are mandatory.
first version
2019-07-20 10:26:52 +00:00
home_dir:
type: string
description: path to the user home directory. The user cannot upload or download files outside this directory. SFTPGo tries to automatically create this folder if missing. Must be an absolute path
uid:
type: integer
format: int32
minimum: 0
maximum: 65535
description: if you run sftpgo as root user the created files and directories will be assigned to this uid. 0 means no change, the owner will be the user that runs sftpgo. Ignored on windows
gid:
type: integer
format: int32
minimum: 0
maximum: 65535
description: if you run sftpgo as root user the created files and directories will be assigned to this gid. 0 means no change, the group will be the one of the user that runs sftpgo. Ignored on windows
max_sessions:
type: integer
format: int32
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: limit the sessions that an user can open. 0 means unlimited
first version
2019-07-20 10:26:52 +00:00
quota_size:
type: integer
format: int64
add a basic web interface The builtin web interface allows to manage users and connections
2019-10-07 16:19:01 +00:00
description: quota as size in bytes. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
first version
2019-07-20 10:26:52 +00:00
quota_files:
type: integer
format: int32
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTP/SCP otherwise a quota scan is needed
first version
2019-07-20 10:26:52 +00:00
permissions:
type: array
items:
$ref: '#/components/schemas/Permission'
minItems: 1
used_quota_size:
type: integer
format: int64
used_quota_file:
type: integer
format: int32
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
last_quota_update:
first version
2019-07-20 10:26:52 +00:00
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: last quota update as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
upload_bandwidth:
type: integer
format: int32
description: Maximum upload bandwidth as KB/s, 0 means unlimited
download_bandwidth:
type: integer
format: int32
description: Maximum download bandwidth as KB/s, 0 means unlimited
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
Transfer:
first version
2019-07-20 10:26:52 +00:00
type: object
properties:
operation_type:
type: string
enum:
- upload
- download
sftpd stats: add file path for active upload/download
2019-08-08 17:33:16 +00:00
path:
type: string
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: SFTP/SCP file path for the upload/download
first version
2019-07-20 10:26:52 +00:00
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: start time as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
size:
type: integer
format: int64
description: bytes transferred
last_activity:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: last transfer activity as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
ConnectionStatus:
type: object
properties:
username:
type: string
description: connected username
connection_id:
type: string
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: unique connection identifier
first version
2019-07-20 10:26:52 +00:00
client_version:
type: string
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: SFTP/SCP client version
first version
2019-07-20 10:26:52 +00:00
remote_address:
type: string
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: Remote address for the connected SFTP/SCP client
first version
2019-07-20 10:26:52 +00:00
connection_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: connection time as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
last_activity:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: last client activity as unix timestamp in milliseconds
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
protocol:
type: string
enum:
- SFTP
- SCP
first version
2019-07-20 10:26:52 +00:00
active_transfers:
type: array
items:
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
$ref : '#/components/schemas/Transfer'
first version
2019-07-20 10:26:52 +00:00
QuotaScan:
type: object
properties:
username:
type: string
description: username with an active scan
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: scan start time as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
ApiResponse:
type: object
properties:
status:
type: integer
format: int32
minimum: 200
maximum: 500
example: 200
description: HTTP Status code, for example 200 OK, 400 Bad request and so on
message:
type: string
nullable: true
description: additional message if any
error:
type: string
nullable: true
description: error description if any
add version info
2019-08-08 08:01:33 +00:00
VersionInfo:
type: object
properties:
version:
type: string
build_date:
type: string
commit_hash:
type: string
Reference in a new issue Copy permalink