directus / directus/directus

fix(specs): add missing methods to `/server`, `/files`, and `/flows`

Open
#27,765 4 comments 0 reactions 1 assignee Claimed by @kheiner View on GitHub
Bug Integrations Low Impact Low Reach OpenAPI
Dominant language
TypeScript
Stars
37.9k
Forks
4.9k
Avg merge
3d 21h
Merged PRs (30d)
36

Description

Part of the spec drift audit tracked in directus/directus#27700.

> < />!IMPORTANT< />
This work requires work from directus/directus#27766 to be addressed first.

## Scope

Three separate controllers expose routes that are absent from the spec: a health check endpoint on `/server`, a remote file import on `/files`, and webhook trigger routes on `/flows`. These are useful standalone operations bundled into one PR because each adds only one or two operations to an already-documented path.

## Routes to document

`/server` (`api/src/controllers/server.ts`)

* `GET /server/health`: returns `200` when healthy or `503` when degraded; only available when `HEALTHCHECK_ENABLED` is not `false`; document using the same ENV-gating pattern introduced in directus/directus#27766

`/files` (`api/src/controllers/files.ts`)

* `POST /files/import`: imports a file from a remote URL; accepts `url` (required), optional `data` and `filterMimeType`

`/flows` (`api/src/controllers/flows.ts`)

* `GET /flows/trigger/{id}`: trigger a flow via GET webhook
* `POST /flows/trigger/{id}`: trigger a flow via POST webhook

## Implementation notes

For each route, locate the existing path YAML file under `packages/specs/src/paths/` and add the new operation block alongside existing operations.

For `GET /server/health`: add an `x-directus-env-gate` extension (or equivalent ENV-gating mechanism) consistent with how `/metrics` was documented in directus/directus#27316. Responses should include both `200` (healthy) and `503` (degraded) schemas.

For `POST /files/import`: add a `requestBody` with the `url`, `data`, and `filterMimeType` fields. Response schema mirrors the single-file response already defined for `GET /files/{id}`.

For the `/flows/trigger/{id}` operations: both accept arbitrary payloads and return whatever the flow returns; use a permissive schema (or reference an existing webhook response type if one exists).

## Verification

Run `pnpm validate` in `packages/specs` and confirm it passes clean. Verify in a Swagger viewer that the three new path entries appear with correct operation descriptions and, for `GET /server/health`, that the ENV-gate annotation is visible.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.