343 lines
10 KiB
YAML
343 lines
10 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Packs Site API
|
|
description: |
|
|
API for the Packs Site. All endpoints are behind the site's gate (master
|
|
password) and most require authentication.
|
|
|
|
## Authentication
|
|
|
|
Requests authenticate with an API token in the `Authorization` header:
|
|
|
|
Authorization: Bearer <username> <token>
|
|
|
|
Tokens are created on the **API Tokens** settings page. Without a valid
|
|
token (or a logged-in browser session) API requests get a `401` response.
|
|
Staff-only endpoints return `403` for non-staff.
|
|
version: 1.0.0
|
|
servers:
|
|
- url: /
|
|
tags:
|
|
- name: Files
|
|
description: Serving stored files
|
|
- name: Uploads
|
|
description: Draft/temp upload management
|
|
- name: Drafts
|
|
description: Create-page autosave
|
|
- name: Search
|
|
description: Autocomplete endpoints
|
|
- name: Packs
|
|
description: Pack update-check
|
|
- name: Stats
|
|
description: Server statistics
|
|
paths:
|
|
/api/files/{file_id}/:
|
|
get:
|
|
tags: [Files]
|
|
summary: Serve a stored file
|
|
description: Serves any stored file (media, release zips, textures). Use `download=1` to force an attachment.
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
required: true
|
|
description: UUID of the stored file.
|
|
schema: { type: string, format: uuid }
|
|
- name: download
|
|
in: query
|
|
required: false
|
|
description: Set to `1` to force a download attachment.
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: The file contents.
|
|
content:
|
|
application/octet-stream:
|
|
schema: { type: string, format: binary }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: File not found.
|
|
/api/uploads/:
|
|
post:
|
|
tags: [Uploads]
|
|
summary: Upload a temporary file
|
|
description: Uploads a file into the current draft / upload pool. Returns the upload record used by the create-page UI.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
description: The file to upload.
|
|
kind:
|
|
type: string
|
|
enum: [thumbnail, version, media]
|
|
default: media
|
|
draft_uuid:
|
|
type: string
|
|
format: uuid
|
|
description: Scope the upload to a specific create-page draft (optional).
|
|
responses:
|
|
"200":
|
|
description: Upload accepted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TempUpload"
|
|
"400":
|
|
description: Invalid file type for the requested kind.
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
/api/uploads/{upload_uuid}/delete/:
|
|
post:
|
|
tags: [Uploads]
|
|
summary: Delete a temporary upload
|
|
description: Removes a pending upload and its stored file. Only the owner may delete it.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: upload_uuid
|
|
in: path
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Deleted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success: { type: boolean }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Upload not found.
|
|
/api/draft/:
|
|
get:
|
|
tags: [Drafts]
|
|
summary: Load a draft
|
|
description: Returns the saved form data and pending uploads for one draft.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: draft
|
|
in: query
|
|
required: true
|
|
description: The draft UUID.
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Draft data + uploads.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DraftData"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Draft not found or not owned by you.
|
|
post:
|
|
tags: [Drafts]
|
|
summary: Autosave a draft
|
|
description: Persists the create-page form fields for a draft (debounced autosave).
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [draft]
|
|
properties:
|
|
draft:
|
|
type: string
|
|
format: uuid
|
|
data:
|
|
type: object
|
|
description: Form fields (title, summary, category, description, tags, version_name, changelog).
|
|
responses:
|
|
"200":
|
|
description: Saved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
saved: { type: boolean }
|
|
updated_at: { type: string, format: date-time }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Draft not found or not owned by you.
|
|
delete:
|
|
tags: [Drafts]
|
|
summary: Delete a draft
|
|
description: Deletes the draft and purges its pending uploads.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: draft
|
|
in: query
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Deleted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success: { type: boolean }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Draft not found or not owned by you.
|
|
/api/tags/autocomplete/:
|
|
get:
|
|
tags: [Search]
|
|
summary: Tag autocomplete
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: false
|
|
description: Partial tag or category name.
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Matching tags.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name: { type: string }
|
|
category: { type: string }
|
|
category_name: { type: string }
|
|
color: { type: string }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
/api/users/autocomplete/:
|
|
get:
|
|
tags: [Search]
|
|
summary: User autocomplete
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: false
|
|
description: Partial username.
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Matching usernames.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
username: { type: string }
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
/api/packs/{namespace}/{pack_id}/latest:
|
|
get:
|
|
tags: [Packs]
|
|
summary: Pack update-check
|
|
description: Newest version for a NeedsOfNature pack id (`namespace:pack_id`), used by the mod's auto-updater.
|
|
parameters:
|
|
- name: namespace
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
- name: pack_id
|
|
in: path
|
|
required: true
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Latest version info.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PackLatest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Pack not found.
|
|
/api/stats/:
|
|
get:
|
|
tags: [Stats]
|
|
summary: Server statistics
|
|
description: One-shot server/performance snapshot. Staff only. Responses are cached ~20s server-side.
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
description: Snapshot payload.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Staff only.
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: Authorization
|
|
description: "API token authentication: `Bearer <username> <token>`."
|
|
responses:
|
|
Unauthorized:
|
|
description: Missing or invalid credentials.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
detail: { type: string }
|
|
example: { detail: Unauthorized }
|
|
schemas:
|
|
TempUpload:
|
|
type: object
|
|
properties:
|
|
uuid: { type: string, format: uuid }
|
|
kind: { type: string, enum: [thumbnail, version, media] }
|
|
filename: { type: string }
|
|
content_type: { type: string }
|
|
url: { type: string }
|
|
DraftData:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
additionalProperties: true
|
|
uploads:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/TempUpload"
|
|
PackLatest:
|
|
type: object
|
|
properties:
|
|
namespace: { type: string }
|
|
pack_id: { type: string }
|
|
name: { type: string }
|
|
version: { type: string }
|
|
pack_format: { type: integer, nullable: true }
|
|
created_at: { type: string, format: date-time }
|
|
download_url: { type: string }
|