Import source: backend/src/openapi.yaml
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
This commit is contained in:
arsam
@@ -0,0 +1,523 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: CShare API
|
||||
version: 0.1.0
|
||||
description: |
|
||||
File-sharing API. Ownership is tracked via an HTTP-only session cookie (`cshare_sid`)
|
||||
issued automatically on first request — no login required for basic uploads/downloads.
|
||||
|
||||
servers:
|
||||
- url: /api
|
||||
description: Same-origin (production)
|
||||
- url: http://localhost:4001/api
|
||||
description: Local development
|
||||
|
||||
tags:
|
||||
- name: files
|
||||
description: Upload, list, and delete files
|
||||
- name: links
|
||||
description: Resolve share links and trigger downloads / previews
|
||||
- name: dashboard
|
||||
description: Per-session analytics
|
||||
- name: auth
|
||||
description: Account registration, login, and token refresh
|
||||
- name: admin
|
||||
description: Internal admin endpoints (API-key protected)
|
||||
|
||||
# ── Common response schemas ─────────────────────────────────────────────────
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
adminKey:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: x-admin-key
|
||||
|
||||
schemas:
|
||||
Error:
|
||||
type: object
|
||||
required: [error, code]
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
code:
|
||||
type: string
|
||||
|
||||
FileRecord:
|
||||
type: object
|
||||
required: [id, linkId, originalName, mimeType, sizeBytes, status, uploader, createdAt, expiresAt, views, downloads, shareUrl]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
linkId:
|
||||
type: string
|
||||
example: "aB3xZ"
|
||||
originalName:
|
||||
type: string
|
||||
example: "report.pdf"
|
||||
mimeType:
|
||||
type: string
|
||||
example: "application/pdf"
|
||||
sizeBytes:
|
||||
type: integer
|
||||
example: 2048000
|
||||
status:
|
||||
type: string
|
||||
enum: [uploaded, deleted, expired]
|
||||
uploader:
|
||||
type: string
|
||||
example: "You"
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
expiresAt:
|
||||
type: string
|
||||
format: date-time
|
||||
views:
|
||||
type: integer
|
||||
downloads:
|
||||
type: integer
|
||||
shareUrl:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://file.asabbagh.com/preview/aB3xZ"
|
||||
|
||||
DashboardStats:
|
||||
type: object
|
||||
required: [totalFiles, totalViews, totalDownloads, events]
|
||||
properties:
|
||||
totalFiles:
|
||||
type: integer
|
||||
totalViews:
|
||||
type: integer
|
||||
totalDownloads:
|
||||
type: integer
|
||||
events:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
linkId:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [view, download]
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
ip:
|
||||
type: string
|
||||
userAgent:
|
||||
type: string
|
||||
|
||||
User:
|
||||
type: object
|
||||
required: [id, email, plan, verified]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
plan:
|
||||
type: string
|
||||
enum: [free, pro, team]
|
||||
verified:
|
||||
type: boolean
|
||||
|
||||
# ── Paths ────────────────────────────────────────────────────────────────────
|
||||
|
||||
paths:
|
||||
|
||||
/v1/files/upload:
|
||||
post:
|
||||
tags: [files]
|
||||
summary: Upload a file
|
||||
description: |
|
||||
Streams the file directly to Google Drive — no disk writes on the server.
|
||||
Rate limited to **20 uploads per IP per hour**.
|
||||
Files blocked by MIME type: EXE, DLL, COM, ELF, MSI.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [file]
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
expiresIn:
|
||||
type: integer
|
||||
description: Expiry in seconds (3 600 – 7 776 000, default 2 592 000)
|
||||
default: 2592000
|
||||
uploader:
|
||||
type: string
|
||||
description: Display name shown to recipients (max 80 chars)
|
||||
default: "You"
|
||||
responses:
|
||||
"201":
|
||||
description: File uploaded
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/FileRecord"
|
||||
"400":
|
||||
description: Missing file or not multipart
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"413":
|
||||
description: File exceeds size limit (500 MB)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"415":
|
||||
description: Blocked file type (executable)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"429":
|
||||
description: Rate limit exceeded
|
||||
headers:
|
||||
Retry-After:
|
||||
schema:
|
||||
type: integer
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
/v1/files:
|
||||
get:
|
||||
tags: [files]
|
||||
summary: List your files
|
||||
description: Returns only files uploaded in the current browser session (scoped by `cshare_sid` cookie).
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
- name: limit
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 100
|
||||
maximum: 100
|
||||
responses:
|
||||
"200":
|
||||
description: Paginated file list
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/FileRecord"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
page:
|
||||
type: integer
|
||||
limit:
|
||||
type: integer
|
||||
total:
|
||||
type: integer
|
||||
|
||||
/v1/files/{id}:
|
||||
get:
|
||||
tags: [files]
|
||||
summary: Get a single file record
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: File record
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/FileRecord"
|
||||
"404":
|
||||
description: File not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
delete:
|
||||
tags: [files]
|
||||
summary: Delete a file
|
||||
description: Only the session that uploaded the file can delete it.
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"204":
|
||||
description: Deleted
|
||||
"404":
|
||||
description: File not found or not owned by this session
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
/v1/links/{linkId}:
|
||||
get:
|
||||
tags: [links]
|
||||
summary: Resolve a share link
|
||||
description: Returns file metadata for the share-link page. Increments view counter.
|
||||
parameters:
|
||||
- name: linkId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
example: "aB3xZ"
|
||||
responses:
|
||||
"200":
|
||||
description: File metadata
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/FileRecord"
|
||||
"404":
|
||||
description: Link not found or expired
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
/v1/links/{linkId}/download:
|
||||
get:
|
||||
tags: [links]
|
||||
summary: Download a file
|
||||
description: Increments download counter then issues a 302 redirect to the Google Drive download URL.
|
||||
parameters:
|
||||
- name: linkId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"302":
|
||||
description: Redirect to Google Drive download
|
||||
headers:
|
||||
Location:
|
||||
schema:
|
||||
type: string
|
||||
format: uri
|
||||
"404":
|
||||
description: Link not found or expired
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"429":
|
||||
description: Rate limit exceeded
|
||||
|
||||
/v1/links/{linkId}/preview:
|
||||
get:
|
||||
tags: [links]
|
||||
summary: Inline preview stream
|
||||
description: |
|
||||
Streams file content for in-browser preview (images, video, audio, text, PDF).
|
||||
Only available for files ≤ 25 MB with a supported MIME type.
|
||||
Content-Security-Policy is set to restrict the preview context.
|
||||
parameters:
|
||||
- name: linkId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: File content stream
|
||||
headers:
|
||||
Content-Type:
|
||||
schema:
|
||||
type: string
|
||||
Content-Disposition:
|
||||
schema:
|
||||
type: string
|
||||
"404":
|
||||
description: Link not found or expired
|
||||
"413":
|
||||
description: Preview not available (file too large or unsupported type)
|
||||
|
||||
/v1/dashboard/stats:
|
||||
get:
|
||||
tags: [dashboard]
|
||||
summary: Session-scoped analytics
|
||||
description: Returns aggregated stats (total files, views, downloads) and recent events for the current session only.
|
||||
responses:
|
||||
"200":
|
||||
description: Dashboard stats
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/DashboardStats"
|
||||
|
||||
/auth/register:
|
||||
post:
|
||||
tags: [auth]
|
||||
summary: Create an account
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
minLength: 8
|
||||
responses:
|
||||
"201":
|
||||
description: Account created — returns access token + sets refresh cookie
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
$ref: "#/components/schemas/User"
|
||||
accessToken:
|
||||
type: string
|
||||
"400":
|
||||
description: Validation error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"429":
|
||||
description: Auth rate limit (5 per 15 min per IP)
|
||||
|
||||
/auth/login:
|
||||
post:
|
||||
tags: [auth]
|
||||
summary: Log in
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: Logged in — access token + refresh cookie
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
$ref: "#/components/schemas/User"
|
||||
accessToken:
|
||||
type: string
|
||||
"401":
|
||||
description: Invalid credentials
|
||||
"429":
|
||||
description: Auth rate limit
|
||||
|
||||
/auth/refresh:
|
||||
post:
|
||||
tags: [auth]
|
||||
summary: Refresh access token
|
||||
description: Reads the `cshare_refresh` HTTP-only cookie. Returns a new access token and rotates the refresh token.
|
||||
responses:
|
||||
"200":
|
||||
description: New access token issued
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
accessToken:
|
||||
type: string
|
||||
"401":
|
||||
description: Missing or expired refresh token
|
||||
|
||||
/auth/logout:
|
||||
post:
|
||||
tags: [auth]
|
||||
summary: Log out
|
||||
description: Revokes the current refresh token and clears the cookie.
|
||||
responses:
|
||||
"204":
|
||||
description: Logged out
|
||||
|
||||
/admin/overview:
|
||||
get:
|
||||
tags: [admin]
|
||||
summary: Admin overview
|
||||
security:
|
||||
- adminKey: []
|
||||
responses:
|
||||
"200":
|
||||
description: File and user statistics
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
filesByStatus:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: integer
|
||||
users:
|
||||
type: integer
|
||||
totalEvents:
|
||||
type: integer
|
||||
"401":
|
||||
description: Missing or invalid admin key
|
||||
Reference in New Issue
Block a user