Skip to content

Andcool-Systems/File-uploader

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

File Uploader

The file uploader is implemented in the Python programming language using FastAPI. All uploaded files are stored on the server. The API provides the ability to preview and download files based on their file extensions.

New Feature!

Upload a .txt file containing only the full link to a resource to shorten it! (The service will automatically redirect you to the specified link when you follow a link to a txt file)

API Documentation

The API is currently hosted at fu.andcool.ru.
Page redirection is handled through the nginx proxy server. The API consists of 2 pathes:

  • /file/ – Endpoint where all files are located.
  • /api/ – Main API endpoint

1.1 Authorization Errors

All requests requiring the Authorization header may encounter errors related to authorization issues.
The Authorization header should have the format Authorization: Bearer <token>.

Response Example

All errors of this type follow a consistent response format and always return an HTTP code of 401.
This section will be referred to as 1.1 in the documentation.

{
    "status": "error",
    "message": "Auth error",
    "auth_error": {
        "message": "error message",
        "errorId": <error code>
    }
}

List of errors:

errorId message Reasons
-1 No Authorization header provided The request is missing the Authorization header
-2 Authorization header must have Bearer <token> format The Authorization header has an incorrect format
-3 Access token expired The token has expired
-4 Invalid access token The token cannot be decrypted
-5 Token not found The token is not found

1.2 Basic API

Retrieve a file based on the URL.

GET /file/<file_url> or GET /f/<file_url>
Successful execution returns a 200 status code and the binary file with the Content-Type.
If the file type cannot be determined, the API returns the file in download mode.

Possible Errors

Error Code Description Possible Reasons
404 File not found The file referenced by the code does not exist

Upload a file to the server

POST /api/upload/{group_id}?include_ext=false
The request body should contain the file to be uploaded.
Only one file is allowed, and its size should not exceed 100MB.
The maximum request frequency is 2 per minute.

Query params:

The group_id parameter indicates the group to which the file should be uploaded. The parameter can take the value private, which means that the file must be linked to a personal account. When passing the group_id parameter other than the private Authorization header is required.

Request body:

The Content-Type header of the request must be a multipart/form-data
The file must be have file key in request body.
The query parameter include_ext can be set to true/false to indicate whether the file extension should be included in the file URL.

Request headers:

The request can also include the Authorization header, containing the user's unique token. If the token is not provided or is not valid, the synced field in the response body will be set to false. The file will be uploaded to the server regardless of whether the Authorization header is included in the request. The auth_error field in the response body contains the authentication error (section 1.1), and if there is no error, the field will be {}.

Response Example

On successful execution, the API returns a 200 HTTP code along with a JSON response.

{
    "status": "success",
    "message": "File uploaded successfully",
    "file_url": "4yn-8yjhsu",
    "file_url_full": "https://fu.andcool.ru/file/4yn-8yjhsu",
    "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1",
    "ext": ".mp4",
    "user_filename": "test.mp4",
    "synced": true,
    "auth_error": {}
}

Possible Errors

Error Code message Possible Reasons
400 No file uploaded No file is given in the request body
413 File size exceeds the limit (100MB) The file size exceeds 100MB
400 Invalid group id group_id parameter contains non-numerical value
404 Group not found The group wuth provided group_id not found
403 You are not in the group Group is exists, but you are has not permissions to upload files in this group

Delete a file

GET /api/delete/<file_url>?key=<unique key>
Successful execution returns a 200 status code, removing the file from the server.

Possible Errors

Error Code Description Possible Reasons
404 File not found The file for deletion is not found
400 Invalid unique key The provided unique key is invalid

1.2 Authorization API

Login and register

POST /api/register
POST /api/login
Request limit per minute: 10 times.
Both requests accept the same request body but have different errors.

A Boolean value can be passed to the optional query parameter bot. When bot is true, a token with a lifetime of 6 months will be generated.

Request Example

{
    "username": "My cool username",
    "password": "My cool password"
}

Successful execution returns a 200 HTTP code, indicating successful registration / login.

{
    "status": "success",
    "accessToken": "<token>",
    "username": "My cool username",
    "message": "logged in with password"
}

Possible Errors

Common for both requests:

errorId HTTP code message Reasons
2 400 No username/password provided Username/password fields are missing in the request

Errors for /register:

errorId HTTP code message Reasons
1 400 An account with this name is already registered A user with the given username already exists

Errors for /login:

errorId HTTP code message Reasons
3 403 Wrong password Incorrect password
4 404 User not found Username not found

Refreshe the token

POST /api/refresh_token
Request limit per minute: 10 times.
The request body includes the accessToken field containing only the token (without Bearer).
Successful execution returns a 200 HTTP code along with the accessToken field in the request body, containing the new token.

Possible Errors

errorId HTTP code message Reasons
5 400 No access token provided The accessToken field is missing in the request

Errors described in section 1.1 may also occur.

Log out of the account

POST /api/logout
Request limit per minute: 10 times.
Endpoint takes the Authorization header containing the access token.
Successful execution of the request deletes the provided token and returns a 200 HTTP code

Possible Errors

Errors described in section 1.1 may occur as well.

Get a list of files.

GET /api/get_files/{group_id}
It takes the Authorization header containing the access token.
Retrieves a list of all files associated with this account.

The group_id parameter shows which group to get the files from. If the parameter is set to private, the files will be taken from a personal account, otherwise Authorization header is required

Response Example

{
    "status": "success",
    "message": "files got successfully",
    "username": "My cool username",
    "is_group_owner": true,
    "data": [
        {
            "file_url": "4yn-8yjhsu",
            "file_url_full": "https://fu.andcool.ru/file/4yn-8yjhsu",
            "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1",
            "ext": ".mp4",
            "user_filename": "test.mp4",
            "creation_date": "1.1.1971",
            "synced": true
        },
        {
            "file_url": "4yn-8yjhsR",
            "file_url_full": "https://fu.andcool.ru/file/4yn-8yjhsR",
            "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1",
            "ext": ".mp4",
            "user_filename": "test1.mp4",
            "creation_date": "1.1.1971",
            "synced": true
        }
    ]
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
400 Invalid group id group_id parameter contains non-numerical value
404 Group not found The group wuth provided group_id not found
403 You are not in the group Group is exists, but you are has not permissions to upload files in this group

Transfer local files to an account.

POST /api/transfer
It takes the Authorization header containing the access token.

The request transfers local files to the account. The endpoint takes files from the data field in the request body and sequentially binds each file to an account. If the binding of any file failed, then these files will be returned in the response body in the unsuccess field. The file is transferred by their file_url and key

Request body example

{   
    "data":[
        {
            "file_url": "4yn-8yjhsu",
            "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1"
        },
        {
            "file_url": "4yn-8yjhsR",
            "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1"
        }
    ]
}

Response example

{
    "status": "success",
    "message": "transfered", 
    "unsuccess": [
        {
            "file_url": "4yn-8yjhsR",
            "key": "6b9a1c1b-5594-4cb9-8d49-99a4c28782a1"
        }
    ]
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
400 Couldn't parse request body No request body provided
400 No data field in request body Couldn't not find data field in request body

Groups

Create file group

POST /api/create_group
It takes the Authorization header containing the access token.

Creates a group with the passed name. The maximum length of a group name is 50 characters.

Request body example

{   
    "group_name": "New group"
}

Response example

{
    "status": "success",
    "message": "created",
    "name": "New group",
    "group_id": 12345678,
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
400 No group_name provided Couldn't not find group_name field in request body
400 Group name length exceeded (50 chars) Too long group name

Delete file group

DELETE /api/delete_group/{group_id}
It takes the Authorization header containing the access token.

Deletes a group with the passed group_id.

Response example

{
    "status": "success", 
    "message": "deleted"
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
404 Group not found Group with passed group_id not found
403 You dont have any permissions to delete this group You are not owner of this group

Generate a new invite link

GET /api/generate_invite/{group_id}
It takes the Authorization header containing the access token.

Generates a invite link for group with the passed group_id.

Response example

{
    "status": "success",
    "message": "created",
    "invite_link": "https://fu.andcool.ru/invite/DSAfd4-hpoqFDFj"
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
404 Group not found Group with passed group_id not found
403 You dont have any permissions You are not owner of this group

Join to a group

POST /api/join/{invite_link}
It takes the Authorization header containing the access token.

Joins to a group by passed invite_link.

Response example

{
    "status": "success",
    "message": "created",
    "name": "New group",
    "group_id": 12345678,
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
404 Invite link not found Could not found a invite link
400 You are already in the group You are already in the group

Leave from group

POST /api/leave/{group_id}
It takes the Authorization header containing the access token.

Leaves from group with passed group_id

Response example

{
    "status": "success", 
    "message": "leaved"
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
404 Group not found Group with passed group_id not found
400 You are not in the group You are not in the group

Get info about invite link

GET /api/invite_info/{invite_link}
It takes the Authorization header containing the access token.

Gives an information about group about invite link.

Response example

{
    "status": "success",
    "message": "Info got successfully",
    "name": "New group",
    "group_id": 12345678,
}

Possible Errors

Errors described in section 1.1 may occur as well.

Error Code message Possible Reasons
404 Invite link not found Could not found a invite link

Get all group from account

GET /api/get_groups
It takes the Authorization header containing the access token.

Get list of groups linked to an account.

Response example

{
    "status": "success", 
    "message": "groups got successfully", 
    "groups": [
        {
            "name": "Bim-Bim",
            "group_id": 12345679
        },
        {
            "name": "Bam-Bam",
            "group_id": 12345677
        }
    ]
}

Possible Errors

Errors described in section 1.1 may occur as well.