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/api/schema/openapi.yaml

684 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'
first version
2019-07-20 10:26:52 +00:00
/sftp_connection:
get:
tags:
- connections
summary: Get the active sftp users and info about their uploads/downloads
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_sftp_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'
/sftp_connection/{connectionID}:
delete:
tags:
- connections
summary: Terminate an active SFTP connection
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: close_sftp_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
summary: Returns an array with one or more SFTP users
description: For security reasons password and public key are empty in the response
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
summary: Adds a new SFTP user
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
description: For security reasons password and public key are empty 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
- delete
- rename
- create_dirs
- create_symlinks
description: >
Permissions:
* `*` - all permission are granted
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
* `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
document how to store passwords using bcrypt or pbkdf2 using REST API
2019-08-18 10:52:29 +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 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
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
description: a password or at least one public key are mandatory. For security reasons this field is omitted when you search/get users.
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
description: limit the sessions that an sftp user can open. 0 means unlimited
quota_size:
type: integer
format: int64
description: quota as size. 0 menas unlimited. Please note that quota is updated if files are added/removed via sftp otherwise a quota scan is needed
quota_files:
type: integer
format: int32
description: quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via sftp otherwise a quota scan is needed
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
SFTPTransfer:
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
description: SFTP 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
description: unique sftp connection identifier
client_version:
type: string
description: SFTP client version
remote_address:
type: string
description: Remote address for the connected SFTP client
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
first version
2019-07-20 10:26:52 +00:00
active_transfers:
type: array
items:
$ref : '#/components/schemas/SFTPTransfer'
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