bfile/filed/docs/file_api.swagger.yml

218 lines
7.2 KiB
YAML

openapi: 3.0.3
info:
title: blek! File (fileD) File API
description: |-
This document describes the API of the File API of blek! File fileD.
This API has optional api key authorization, which should be located in the env file.
version: 0.0.1
servers:
- url: http://localhost
description: Local staging environment
tags:
- name: File API
description: API for interacting with files
paths:
/api/files/get_all:
get:
summary: Get all files
description: |-
Get all files available.
Returns an array of file objects with all data
tags:
- File API
security:
- apikey: [ key ]
responses:
200:
description: An array of file objects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/File'
example:
- path: /opt/useruploads/417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a
size: 10
name: null
mime: text/plain
delete_at: '1984-01-01T00:00:00.000Z'
sha512: 417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a
401:
description: |-
This error code is returned if one of the two conditions are met:
1. The instance does not allow getting information about all files.
2. The instance requires API key for all API manipulations.
3. The provided API key is invalid.
4. API authorization is not enabled, but a key is provided
/api/files/delete:
post:
summary: Delete a file
description: |-
Deletes a file thats been uploaded.
It will work if one of the two conditions are met:
1. The requester's IP is the same as the uploader IP
2. The request is authorized with an API key
tags:
- File API
security:
- apikey: [ key ]
responses:
200:
description: |-
The file has been deleted
Returns an empty object for future extension
content:
application/json:
schema:
type: object
example: {}
401:
description: |-
This error code is returned if one of the two conditions are met:
1. The instance does not allow deleting files via API.
2. The file has been uploaded from another IP, which is not this one, and the API was not authorized via an API key.
3. The instance requires API key for all API manipulations.
4. The provided API key is invalid.
5. API authorization is not enabled, but a key is provided
requestBody:
content:
application/json:
schema:
type: object
properties:
fid:
type: string
example: ID or name of the file. It is the NAME in file.blek.codes/uploads/NAME
/api/files/upload:
post:
summary: Upload a file
description: |-
A programmatic way to upload a file.
The request must be encoded in `multipart/form-data` to ensure that the binary file is transferred properly.
tags:
- File API
security:
- apikey: [ key ]
requestBody:
description: |-
A multipart form
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
example: binary file data
description: binary file data
instance_pass:
type: string
example: super_secret_pass
description: Instance-specific password needed to upload files
metadata:
type: object
description: |-
JSON object with file info:
```
{
sha512: string,
name?: string,
pass?: string
}
```
Note that the content type does not matter on this one.
properties:
sha512:
type: string
description: SHA512 hash of the file to ensure integrity
name:
type: string
description: Optional name of the file so it would be accessible like file.blek.codes/uploads/{name}
pass:
type: string
description: Optional password protection for the file
responses:
200:
description: File uploaded successfully
content:
application/json:
schema:
type: object
properties:
status:
example: 'OK'
401:
description: |-
This error code is returned if one of the 4 conditions are met:
1. The instance does not allow API file uploads.
2. The instance requires API key for all API manipulations.
3. The provided API key is invalid.
4. API authorization is not enabled, but a key is provided
content:
application/json:
schema:
type: object
properties:
error:
example: 'APIPasswordDenied'
details:
example: 'API password authorization has been denied.'
403:
description: |-
This error code is returned if your request payload is malformed or the hash doesn't match the file
content:
application/json:
schema:
type: object
properties:
error:
example: 'APIError'
details:
example: 'Request payload invalid'
components:
schemas:
File:
type: object
properties:
path:
type: string
description: Path to the file in fileD's filesystem
example: 1
size:
type: integer
description: Size of the file in bytes
example: 10
name:
type: string
description: (optional) Name of the file
example: null
mime:
type: string
description: MIME type of the file
example: text/plain
delete_at:
type: string
description: TimeDate when the file will be deleted
example: '1984-01-01T00:00:00.000Z'
sha512:
type: string
example: 417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a
securitySchemes:
apikey:
type: http
scheme: bearer
description: Optional authorization, as defined in the instance-specific config file