984 lines
30 KiB
YAML
984 lines
30 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Pastebin API
|
|
version: 1.1.0
|
|
description: An API for managing and sharing pastes.
|
|
servers:
|
|
- url: https://pastebin.mydomain.com
|
|
description: Production Server
|
|
- url: http://localhost:5000
|
|
description: Local Server
|
|
paths:
|
|
/login:
|
|
post:
|
|
summary: User login
|
|
description: Authenticate a user and start a session.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
password:
|
|
type: string
|
|
required:
|
|
- username
|
|
- password
|
|
responses:
|
|
'200':
|
|
description: Login successful
|
|
'401':
|
|
description: Invalid credentials
|
|
|
|
/logout:
|
|
get:
|
|
summary: Logout the current user
|
|
description: Logs out the authenticated user.
|
|
responses:
|
|
'200':
|
|
description: User logged out successfully.
|
|
|
|
/register:
|
|
post:
|
|
summary: Register a new user
|
|
description: Allows an admin to register a new user.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
password:
|
|
type: string
|
|
required:
|
|
- username
|
|
- password
|
|
responses:
|
|
'201':
|
|
description: User registered successfully
|
|
'400':
|
|
description: Invalid input
|
|
'403':
|
|
description: Unauthorized access
|
|
/paste:
|
|
post:
|
|
summary: Create a new paste
|
|
description: Upload a new paste, either as text or a file. The paste can be private, expire in 1 day, or be permanent.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
c:
|
|
type: string
|
|
format: binary
|
|
description: The content or file to upload
|
|
lang:
|
|
type: string
|
|
description: Programming language for syntax highlighting
|
|
expire:
|
|
type: string
|
|
enum: [yes, no]
|
|
default: yes
|
|
description: >
|
|
Whether the paste should expire after 1 day.
|
|
- `yes` (default): The paste will expire in 24 hours.
|
|
- `no`: The paste will be permanent.
|
|
private:
|
|
type: string
|
|
enum: [yes, no]
|
|
default: no
|
|
description: >
|
|
Whether the paste should be private.
|
|
- `yes`: The paste will only be accessible to the creator and shared users.
|
|
- `no` (default): The paste will be public.
|
|
responses:
|
|
'201':
|
|
description: Paste created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: The URL of the created paste
|
|
'400':
|
|
description: Missing content or invalid data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
'403':
|
|
description: Unauthorized access or user exceeded quota
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Authorization error message
|
|
|
|
/paste/{id}:
|
|
get:
|
|
summary: Retrieve a paste by ID
|
|
description: Fetches the paste content if accessible to the user.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Paste retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
filename:
|
|
type: string
|
|
language:
|
|
type: string
|
|
content_type:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
'403':
|
|
description: Unauthorized access
|
|
'404':
|
|
description: Paste not found
|
|
|
|
/paste/{id}/raw:
|
|
get:
|
|
summary: Get raw paste content
|
|
description: Retrieve the raw content of a paste, either as plain text or binary.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Raw content retrieved successfully
|
|
'404':
|
|
description: Paste not found
|
|
|
|
/pastes:
|
|
get:
|
|
summary: List user pastes
|
|
description: Retrieve a list of all pastes created by the authenticated user.
|
|
responses:
|
|
'200':
|
|
description: List of pastes retrieved successfully
|
|
'401':
|
|
description: Unauthorized access
|
|
|
|
/stats:
|
|
get:
|
|
summary: Paste Statistics
|
|
description: Returns either an HTML page with visual statistics or JSON data based on the query parameter `format`.
|
|
parameters:
|
|
- name: format
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum: [html, json]
|
|
default: html
|
|
responses:
|
|
'200':
|
|
description: Statistics response
|
|
'400':
|
|
description: Invalid query parameters
|
|
|
|
/user/details:
|
|
get:
|
|
summary: Get current user details
|
|
description: Retrieves the current user's role, storage used, and remaining storage.
|
|
responses:
|
|
'200':
|
|
description: User details retrieved successfully
|
|
'401':
|
|
description: Unauthorized access
|
|
|
|
/change-password:
|
|
post:
|
|
summary: Change user password
|
|
description: Allows the authenticated user to change their password.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
current_password:
|
|
type: string
|
|
new_password:
|
|
type: string
|
|
confirm_password:
|
|
type: string
|
|
required:
|
|
- current_password
|
|
- new_password
|
|
- confirm_password
|
|
responses:
|
|
'200':
|
|
description: Password updated successfully
|
|
'400':
|
|
description: Validation errors
|
|
'401':
|
|
description: Unauthorized access or incorrect current password
|
|
|
|
/user/{username}/stats:
|
|
get:
|
|
summary: Get user statistics
|
|
description: Retrieve statistics about a user's pastes.
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
responses:
|
|
'200':
|
|
description: User statistics retrieved successfully
|
|
'404':
|
|
description: User not found
|
|
|
|
/favorites:
|
|
get:
|
|
summary: List user favorites
|
|
description: Retrieve a list of all favorites for the authenticated user.
|
|
responses:
|
|
'200':
|
|
description: Favorites retrieved successfully
|
|
'401':
|
|
description: Unauthorized access
|
|
|
|
/paste/{id}/favorite:
|
|
post:
|
|
summary: Add a paste to favorites
|
|
description: Adds the specified paste to the authenticated user's favorites.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Paste added to favorites
|
|
'404':
|
|
description: Paste not found
|
|
|
|
/paste/{id}/unfavorite:
|
|
post:
|
|
summary: Remove a paste from favorites
|
|
description: Removes the specified paste from the authenticated user's favorites.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Paste removed from favorites
|
|
'404':
|
|
description: Paste not in favorites
|
|
|
|
/pastes/search:
|
|
get:
|
|
summary: Search pastes
|
|
description: Search for pastes by content, content type, and language.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Search query to match paste content.
|
|
- name: content_type
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Filter by the MIME type of the paste.
|
|
- name: language
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Filter by the programming language of the paste.
|
|
responses:
|
|
'200':
|
|
description: Search results retrieved successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique ID of the paste.
|
|
title:
|
|
type: string
|
|
description: Title of the paste.
|
|
content:
|
|
type: string
|
|
description: Content of the paste (truncated for large pastes).
|
|
language:
|
|
type: string
|
|
description: Programming language of the paste.
|
|
content_type:
|
|
type: string
|
|
description: MIME type of the paste.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation date of the paste.
|
|
'400':
|
|
description: Invalid search query or missing parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
'401':
|
|
description: Unauthorized access.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
'500':
|
|
description: Server error while processing the search.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
/api/paste/{id}/favorite:
|
|
post:
|
|
summary: Add a paste to favorites from terminal
|
|
description: Marks the specified paste as a favorite for the authenticated user.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: ID of the paste to mark as favorite.
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'201':
|
|
description: Paste successfully added to favorites.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "Paste added to favorites"
|
|
'400':
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste already in favorites"
|
|
'401':
|
|
description: Unauthorized
|
|
'404':
|
|
description: Paste not found
|
|
'500':
|
|
description: Server error
|
|
/api/paste/{id}/unfavorite:
|
|
post:
|
|
summary: Remove a paste from favorites from terminal
|
|
description: Removes the specified paste from the authenticated user's favorites.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: ID of the paste to remove from favorites.
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Paste successfully removed from favorites.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "Paste removed from favorites"
|
|
'400':
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste not in favorites"
|
|
'401':
|
|
description: Unauthorized
|
|
'404':
|
|
description: Paste not found
|
|
'500':
|
|
description: Server error
|
|
/api/paste/{id}/download:
|
|
get:
|
|
summary: Download a paste
|
|
description: Downloads the file associated with the specified paste. The server returns the original filename in the `Content-Disposition` header for proper file naming.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: ID of the paste to download.
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Successfully downloads the file.
|
|
headers:
|
|
Content-Disposition:
|
|
description: Specifies the filename for the downloaded file.
|
|
schema:
|
|
type: string
|
|
example: attachment; filename="example.txt"
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'400':
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Invalid paste ID"
|
|
'401':
|
|
description: Unauthorized
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "You do not have permission to download this file"
|
|
'404':
|
|
description: Paste not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "File not found"
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Unexpected server error"
|
|
/api/favorites:
|
|
get:
|
|
summary: List user favorites
|
|
description: Retrieve a list of all favorites for the authenticated user.
|
|
responses:
|
|
'200':
|
|
description: Favorites retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: Unique ID of the paste
|
|
url:
|
|
type: string
|
|
description: URL of the paste
|
|
title:
|
|
type: string
|
|
description: Title or filename of the paste
|
|
type:
|
|
type: string
|
|
description: Type of the paste
|
|
size:
|
|
type: integer
|
|
description: Size of the paste in bytes
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation date of the paste
|
|
'401':
|
|
description: Unauthorized access
|
|
'500':
|
|
description: Error retrieving favorites
|
|
/api/shared_with_others:
|
|
get:
|
|
summary: List pastes shared with others
|
|
description: Retrieve a list of pastes that the authenticated user has shared with others.
|
|
responses:
|
|
'200':
|
|
description: Pastes shared with others retrieved successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: Unique ID of the paste.
|
|
title:
|
|
type: string
|
|
description: Title of the paste or filename if title is missing.
|
|
shared_with:
|
|
type: array
|
|
description: List of usernames the paste is shared with.
|
|
items:
|
|
type: string
|
|
can_edit:
|
|
type: boolean
|
|
description: Indicates if the shared user can edit the paste.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation date of the paste.
|
|
'401':
|
|
description: Unauthorized access.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Authorization token is missing or invalid."
|
|
'500':
|
|
description: Server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Unexpected server error."
|
|
/api/shared_with_me:
|
|
get:
|
|
summary: List pastes shared with the user
|
|
description: Retrieve a list of pastes that have been shared with the authenticated user.
|
|
responses:
|
|
'200':
|
|
description: Pastes shared with the user retrieved successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: Unique ID of the paste.
|
|
title:
|
|
type: string
|
|
description: Title of the paste or filename if title is missing.
|
|
owner:
|
|
type: string
|
|
description: Username of the owner who shared the paste.
|
|
can_edit:
|
|
type: boolean
|
|
description: Indicates if the user has edit permissions for the paste.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation date of the paste.
|
|
'401':
|
|
description: Unauthorized access.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Authorization token is missing or invalid."
|
|
'500':
|
|
description: Server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Unexpected server error."
|
|
/api/paste/{id}/unshare:
|
|
post:
|
|
summary: Unshare a paste
|
|
description: Remove the shared permission of a paste for a specific user.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: ID of the paste to unshare.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: The username of the user to unshare the paste with.
|
|
required:
|
|
- username
|
|
responses:
|
|
'200':
|
|
description: Paste successfully unshared.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "Paste successfully unshared with username."
|
|
'400':
|
|
description: Invalid request or paste is not shared with the user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste is not shared with username."
|
|
'404':
|
|
description: Paste or user not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste not found or user not found."
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "An unexpected error occurred."
|
|
details:
|
|
type: string
|
|
example: "Detailed error message."
|
|
/api/paste/{id}:
|
|
put:
|
|
summary: Update existing paste content
|
|
description: Overwrites the content of an existing paste with new data, assuming the user has edit permission.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: ID of the paste to update.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
content:
|
|
type: string
|
|
description: The new content for the paste.
|
|
required:
|
|
- content
|
|
responses:
|
|
'200':
|
|
description: Paste updated successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "Paste updated successfully"
|
|
'400':
|
|
description: Missing or invalid content in the request body.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Missing 'content' in JSON"
|
|
'403':
|
|
description: The user does not have permission to edit this paste.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "No permission to edit this paste."
|
|
'404':
|
|
description: Paste not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste not found"
|
|
'500':
|
|
description: Server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "An unexpected error occurred."
|
|
details:
|
|
type: string
|
|
example: "Detailed traceback or error message."
|
|
/api/paste/{id}/share:
|
|
post:
|
|
summary: Share a paste with another user
|
|
description: Share a specific paste with another user, optionally granting them edit permissions.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: ID of the paste to be shared.
|
|
schema:
|
|
type: integer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: Username of the recipient.
|
|
example: "test_user"
|
|
can_edit:
|
|
type: boolean
|
|
description: Indicates whether the recipient can edit the paste.
|
|
example: true
|
|
required:
|
|
- username
|
|
responses:
|
|
'200':
|
|
description: Paste shared successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "Paste shared successfully with test_user."
|
|
can_edit:
|
|
type: boolean
|
|
example: true
|
|
'400':
|
|
description: Bad request, e.g., if the paste is already shared with the user or invalid data is provided.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste is already shared with test_user."
|
|
'403':
|
|
description: Forbidden, e.g., if the paste does not belong to the authenticated user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "You do not own this paste."
|
|
'404':
|
|
description: Paste or recipient not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "User test_user not found."
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "An unexpected error occurred."
|
|
details:
|
|
type: string
|
|
example: "Detailed error message for debugging."
|
|
/api/removegps:
|
|
post:
|
|
summary: Remove GPS metadata from an image
|
|
description: Removes GPS metadata from an image file owned by the authenticated user.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
paste_id:
|
|
type: integer
|
|
description: ID of the paste containing the image.
|
|
required:
|
|
- paste_id
|
|
responses:
|
|
'200':
|
|
description: GPS metadata successfully removed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
'400':
|
|
description: Missing or invalid paste_id.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Missing paste_id"
|
|
'403':
|
|
description: User does not have permission to modify this paste.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "You do not have permission to modify this file"
|
|
'404':
|
|
description: Paste or file not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Paste not found"
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Error removing GPS metadata"
|
|
|