218 lines
7.2 KiB
YAML
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 |