brett/Zordon
1
0
Fork 0
mirror of https://github.com/blw1138/Zordon.git synced 2026-06-09 13:39:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

REST API endpoint streamlining and cleanup (#133)

Browse Source 
* Consolidate engine_info api calls

* Change api methods to use POST when possible

* Delete engine API cleanup

* Remove redundant installed_engines endpoint

* Update proxy to use similar named methods to new API calls

* More API cleanup

* Jobs API cleanup

* More jobs API cleanup

* Fix add jobs error due to null queue

* Remove unnecessary full_status and snapshot API endpoints

* Streamline add job POST endpoint

* Fix test after method name change
This commit is contained in:
Brett
2026-06-06 12:04:52 -05:00
committed by GitHub
parent 24eb7b5616
commit f0be78adcc
15 changed files with 1255 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+487
View File
@@ -0,0 +1,487 @@
# Zordon API Reference
Zordon exposes a Flask API from `src/api/api_server.py`. The server is started by
`start_api_server()` and listens on `Config.port_number` with all application
routes mounted under `/api`.
The in-repo client wrapper is `src/api/server_proxy.py`. Most UI and distributed
rendering code should prefer `RenderServerProxy` instead of constructing request
URLs directly.
## Versioning
- Current API version: `0.1`
- `RenderServerProxy.request()` sends `X-API-Version` with the current
`API_VERSION`, but the server does not currently validate this header.
## Response Conventions
- JSON endpoints return Flask-serialized dictionaries or lists.
- File endpoints return `send_file()` responses.
- Most error responses are plain text with HTTP `400`, `404`, `500`, or `503`.
- `JobNotFoundError` is mapped to HTTP `400`.
- Unhandled exceptions are mapped to HTTP `500` with a plain-text message.
## Jobs
### `GET /api/jobs`
Returns all render jobs and a cache token.
Response:
```json
{
"jobs": [
{
"id": "job-id",
"name": "job name",
"status": "running"
}
],
"token": "cache-token"
}
```
Known callers:
- `RenderServerProxy.get_jobs()`
- `src/ui/main_window.py`
### `GET /api/jobs/long_poll`
Long-polls the job list until the supplied cache token changes or 30 seconds
elapse.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `token` | No | Cache token returned by `/api/jobs`. |
Responses:
- `200` with the same shape as `/api/jobs` when jobs changed.
- `204` with an empty body when no changes arrive before timeout.
Known callers:
- `RenderServerProxy.get_jobs()` through the background cache updater.
### `GET /api/jobs/status/<status_val>`
Returns jobs matching a render status.
Path parameters:
| Name | Description |
| --- | --- |
| `status_val` | Status string converted by `string_to_status()`. |
Responses:
- `200` with a list of job JSON objects when matches exist.
- `400` when no jobs match the requested status.
Review note: this route is not currently wrapped by `RenderServerProxy` and no
in-repo callers were found.
### `GET /api/jobs/<job_id>`
Returns one job as JSON.
Known callers:
- `RenderServerProxy.get_job()`
- `add_job.py`
- `src/ui/main_window.py`
- `src/distributed_job_manager.py`
- `tests/job_creation_tests.py`
### `GET /api/jobs/<job_id>/logs`
Returns the job log file as `text/plain`.
Known callers:
- `src/ui/main_window.py` opens this URL directly.
### `GET /api/jobs/<job_id>/files`
Returns a list of output filenames for the job.
Known callers:
- `RenderServerProxy.get_job_files()`
- `src/utilities/server_helper.py`
### `GET /api/jobs/<job_id>/download`
Downloads one output file.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `filename` | Yes | Case-insensitive filename from the job file list. |
Responses:
- `200` with the requested file as an attachment.
- `400` when `filename` is missing.
- `404` when the file is not found.
Known callers:
- `RenderServerProxy.download_job_file()`
- `src/utilities/server_helper.py`
### `GET /api/jobs/<job_id>/download_all`
Creates a temporary zip of the job output directory and downloads it.
Known callers:
- `RenderServerProxy.download_all_job_files()`
- `src/ui/main_window.py`
- `src/utilities/server_helper.py`
### `GET /api/jobs/<job_id>/thumbnail`
Returns a generated preview image or video for a job.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `size` | No | `big` selects the larger preview path. Currently parsed but not applied. |
| `video_ok` | No | If truthy and a video preview exists, video can be returned. |
Responses:
- `200` with `image/jpeg` or `video/mp4`.
- `404` when no thumbnail is available.
- `500` on preview generation errors.
Known callers:
- `src/ui/main_window.py`
Review note: `size=big` is parsed into `big_thumb` but not used.
## Job Lifecycle
### `POST /api/jobs`
Adds one or more render jobs.
Request formats:
- JSON request body.
- Multipart form with a `json` field and optional `file` upload.
Common job fields include:
| Name | Description |
| --- | --- |
| `name` | Display name for the render job. |
| `renderer` | Render engine name such as `blender` or `ffmpeg`. |
| `start_frame` | First frame to render. |
| `end_frame` | Last frame to render. |
| `args` | Engine-specific render arguments. |
| `enable_split_jobs` | Whether distributed subjobs may be created. |
| `child_jobs` | Optional subjob definitions. |
| `local_path` | Local file path used when posting to localhost. |
Responses:
- `200` with created job data.
- `400` for invalid or missing job data.
- `500` for unexpected processing or creation errors.
Known callers:
- `RenderServerProxy.create_job()`
- `add_job.py`
- `src/ui/add_job_window.py`
- `src/distributed_job_manager.py`
- `tests/job_creation_tests.py`
### `POST /api/jobs/<job_id>/cancel`
Cancels a job.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `confirm` | Yes | Must be truthy or the request is rejected. |
| `redirect` | No | If truthy, redirects to `index`. |
Known callers:
- `RenderServerProxy.cancel_job()`
- `src/ui/main_window.py`
- `src/distributed_job_manager.py`
### `POST /api/jobs/<job_id>/delete`
Deletes a job, stops it first, deletes previews, and removes owned upload/output
directories when safe.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `confirm` | Yes | Must be truthy or the request is rejected. |
Known callers:
- `RenderServerProxy.delete_job()`
- `src/ui/main_window.py`
### `POST /api/jobs/<job_id>/subjob_update`
Notifies a parent job that a child/subjob changed state.
Request body:
- JSON representation of a subjob.
Known callers:
- `RenderServerProxy.send_subjob_update_notification()`
- `src/distributed_job_manager.py`
## Status and Environment
### `GET /api/heartbeat`
Returns the current timestamp as plain text. Used for fast connectivity checks.
Known callers:
- `RenderServerProxy.check_connection()`
### `GET /api/status`
Returns local system and queue status.
Response includes:
- timestamp
- operating system and version
- CPU brand, count, and current utilization
- memory totals and current utilization
- job counts
- hostname and port
- app and API versions
Known callers:
- `RenderServerProxy.get_status()`
### `GET /api/presets`
Returns `config/presets.yaml`.
Review note: no in-repo callers were found.
### `GET /api/cpu_benchmark`
Runs a CPU benchmark for 10 seconds and returns the score as plain text.
Known callers:
- `src/utilities/server_helper.py`
### `GET /api/disk_benchmark`
Runs a disk I/O benchmark and returns write/read speeds.
Review note: no in-repo callers were found.
## Engines
### `GET /api/engines/for_filename`
Returns the engine name suitable for a project filename.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `filename` | Yes | Project filename or path. The client currently sends only the basename. |
Known callers:
- `RenderServerProxy.get_engine_for_filename()`
- `src/ui/add_job_window.py`
### `GET /api/engines`
Returns installed engine data keyed by engine name.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `response_type` | No | `standard` or `full`; defaults to `standard`. |
`full` responses also include supported extensions, supported export formats,
system info, and UI options.
Known callers:
- `RenderServerProxy.get_engines()`
- `src/ui/settings_window.py`
- `src/ui/engine_browser.py`
### `GET /api/engines/names`
Returns installed engine names as a list without instantiating engine classes.
Use this for lightweight selection UIs that only need engine names.
Known callers:
- `RenderServerProxy.get_engine_names()`
- `src/ui/add_job_window.py`
### `GET /api/engines/<engine_name>`
Returns installed version data for a single engine.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `response_type` | No | `standard` or `full`; defaults to `standard`. |
`full` responses also include supported extensions, supported export formats,
system info, and UI options.
Known callers:
- `RenderServerProxy.get_engine()`
- `src/ui/add_job_window.py`
### `GET /api/engines/<engine_name>/availability`
Returns whether an engine can accept jobs on this server, plus CPU count,
installed versions, and hostname.
Known callers:
- `RenderServerProxy.get_engine_availability()`
- `src/distributed_job_manager.py`
### `GET /api/engines/<engine_name>/args`
Returns engine arguments.
Review note: no in-repo callers were found.
### `GET /api/engines/<engine_name>/help`
Returns engine help text.
Known callers:
- `src/ui/add_job_window.py` opens this URL directly.
### `GET /api/engines/download_available`
Checks whether a managed engine version is available to download.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `engine` | Yes | Engine name. |
| `version` | Yes | Engine version. |
| `system_os` | No | Target OS. |
| `cpu` | No | Target CPU architecture. |
Review note: no in-repo callers were found.
### `GET /api/engines/most_recent_version`
Finds the most recent downloadable version for an engine.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `engine` | Yes | Engine name. |
| `system_os` | No | Target OS. |
| `cpu` | No | Target CPU architecture. |
Review note: no in-repo callers were found.
### `POST /api/engines/download`
Downloads a managed engine version.
Query parameters:
| Name | Required | Description |
| --- | --- | --- |
| `engine` | Yes | Engine name. |
| `version` | Yes | Engine version. |
| `system_os` | No | Target OS. |
| `cpu` | No | Target CPU architecture. |
Review note: no in-repo callers were found. Settings currently calls
`EngineManager.download_engine()` directly instead of this API route.
### `POST /api/engines/delete`
Deletes a managed engine download.
JSON body:
| Name | Required | Description |
| --- | --- | --- |
| `engine` | Yes | Engine name. |
| `version` | Yes | Engine version. |
| `system_os` | No | Target OS. |
| `cpu` | No | Target CPU architecture. |
Known callers:
- `RenderServerProxy.delete_engine_download()`
- `src/ui/engine_browser.py`
## Debug
### `GET /api/_debug/detected_clients`
Returns hostnames detected by Zeroconf.
Review note: development/debug only, with an inline comment saying it probably
should not ship.
### `POST /api/_debug/clear_history`
Clears render queue history and returns `success`.
Review note: development/debug only.
## Redundancy and Cleanup Review
Routes with no in-repo callers found:
- `GET /api/jobs/status/<status_val>`
- `GET /api/presets`
- `GET /api/disk_benchmark`
- `GET /api/engines/<engine_name>/args`
- `GET /api/engines/download_available`
- `GET /api/engines/most_recent_version`
- `POST /api/engines/download`
- `GET /api/_debug/detected_clients`
- `POST /api/_debug/clear_history`
Routes or methods with cleanup risks:
- `job_thumbnail()` parses `size=big` but never uses the resulting `big_thumb`
value.