feat(api): add a REST API with API keys and OpenAPI docs
FR
1d ago+1582+1582+0123456789012345678901234567890123456789-59-59-01234567890123456789
Adds a REST API at /api/v1, so scripts and tools such as n8n can convert files without the web interface. Closes #363.
What it adds
- Convert one file.
POST /api/v1/converttakes a file and a target format and responds with the converted file. - Jobs for several files.
POST /api/v1/jobsstarts a job and returns202with aLocationheader.GET /api/v1/jobs/{id}reports each file's status and links its results, which download one by one (/files/{name}) or together as a tar (/archive).GET /api/v1/jobslists jobs, newest first, andDELETE /api/v1/jobs/{id}removes a job with its files. - Formats.
GET /api/v1/targets?from=docxlists what a format can become, and which converters can do it.GET /api/v1/converterslists every converter with what it reads and writes. - API keys. A new page at
/account/api-keyscreates and revokes keys. It's linked from the header and the account page. A key is shown once. Only its SHA-256 hash is stored, with a short prefix so people can tell keys apart, and the time it was last used. Requests send it asAuthorization: Bearer <key>orX-API-Key: <key>. - Docs. An OpenAPI description at
/api/v1/openapi.json, and Swagger UI at/api/v1/docs. Only the API is documented, not the web pages. The README gets an "API" section.
Errors are JSON: { "error": "<code>", "message": "<explanation>" }. For example, 422 unsupported_conversion names the converters that can do the conversion when the requested one can't.
Testing
- 20 new tests in
tests/api/api.test.ts, using the existingtests/preload.tssetup. They cover keys (including that only a hash is stored and revoking locks a key out), both ways of converting, jobs, downloads and archives, deletion, users not seeing each other's jobs, error responses, and the OpenAPI document. bun run lintandbun run testpass (484 tests).- Built the Docker image and used every endpoint against it: created a key on the keys page, converted SVG to PNG, Markdown to Word and Word to PDF with curl, ran a two-file job, downloaded its files and archive, and deleted it.