fix(specs): add missing methods to `/server`, `/files`, and `/flows`
- 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
Assessment
This issue has not been assessed yet.