# Public PDF API A public REST API for converting arbitrary HTML and CSS to PDF. This API is independent of book content and can be used by any external system. It proxies requests to the WeasyPrint-based PDF server. The API requires a dedicated API key for authentication and provides an asynchronous conversion workflow: start a job, poll for status, download the result. ## Configuration Environment variables: - `PDFSERVER_URL` - PDF server URL (default: `http://localhost:8040`) Registry records: - `wcs.backend.pdfserver.pub.apikey` - The API key that clients must provide. Configurable via the Plone control panel or GenericSetup registry export. ## Authentication All requests must include the `X-PDFServer-API-Key` header with a valid key. Requests with a missing, invalid, or unconfigured API key receive a `401 Unauthorized` response: ```json { "error": "Invalid or missing API key" } ``` ## Endpoints ### POST @pdfserver-pub-convert Starts an asynchronous HTML-to-PDF conversion. ```javascript const response = await fetch('https://example.com/@pdfserver-pub-convert', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'X-PDFServer-API-Key': '', }, body: JSON.stringify({ html: '

Hello

', css: 'h1 { color: navy; }', filename: 'report.pdf', }), }); ``` ```python import requests response = requests.post( 'https://example.com/@pdfserver-pub-convert', headers={ 'Accept': 'application/json', 'Content-Type': 'application/json', 'X-PDFServer-API-Key': '', }, json={ 'html': '

Hello

', 'css': 'h1 { color: navy; }', 'filename': 'report.pdf', }, ) ``` Request Body: | Field | Required | Description | |---|---|---| | `html` | Yes | HTML content to convert. | | `css` | No | CSS stylesheet as a string. Defaults to empty. | | `filename` | No | Output filename. Defaults to `output.pdf`. | Response (200): ```json { "uid": "550e8400-e29b-41d4-a716-446655440000", "filename": "report.pdf", "status": "running" } ``` ### GET @pdfserver-pub-status Polls the conversion job status. ```javascript const status = await fetch( 'https://example.com/@pdfserver-pub-status?uid=550e8400-...', { headers: { 'Accept': 'application/json', 'X-PDFServer-API-Key': '', }, } ); ``` Query Parameters: - `uid` (required) - The job UID returned by the convert endpoint. Response (200): ```json { "uid": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "filename": "report.pdf", "download": "/pdf/550e8400-e29b-41d4-a716-446655440000" } ``` Possible `status` values: `running`, `completed`, `failed`. ### GET @pdfserver-pub-download Downloads the generated PDF once the job status is `completed`. ```javascript const pdf = await fetch( 'https://example.com/@pdfserver-pub-download?uid=550e8400-...', { headers: { 'X-PDFServer-API-Key': '' } } ); const blob = await pdf.blob(); ``` Query Parameters: - `uid` (required) - The job UID returned by the convert endpoint. Response: Binary PDF file with `Content-Type: application/pdf`. ## File Locations - `wcs/backend/pdfserver_pub/restapi.py` - REST API endpoints - `wcs/backend/pdfserver_pub/auth.py` - API key validation - `wcs/backend/pdfserver_pub/configure.zcml` - ZCML registration - `wcs/backend/book/pdfserver_client.py` - PDF server client (shared with book PDF export)