API Documentation

This page documents the wiki's JSON HTTP API: available endpoints, expected requests and responses, and authentication notes.

All API endpoints are rooted under /api and return JSON (or appropriate HTTP status codes). The API is intentionally small and mirrors the actions available in the web UI.

Authentication

• The API uses the same session-based authentication as the web UI. Log in via the web form at /login (POST form fields username and password) to obtain a session cookie. Subsequent API requests should send that cookie.
• If you are a site administrator (determined by LDAP group membership), your session will include is_admin and you can access admin-only endpoints such as DELETE.
• Unauthenticated requests will receive HTTP 401 responses for endpoints that require login.

Examples (using curl and a cookie jar):

# Log in (interactive web form also works). Replace credentials as appropriate.
curl -c cookies.txt -d "username=alice" -d "password=secret" -X POST https://example.org/login

# Use the saved cookie for API calls
curl -b cookies.txt https://example.org/api/pages

Endpoints

GET /api/pages

Return a list of available page base names.

Response example

{ "pages": ["Home", "About", "Linux_Router_HOWTO"] }

GET /api/pages/

Return JSON with name, markdown (source if present) and html (rendered HTML if present). name should be a URL-encoded page name (page filenames use underscores; the API accepts either underscored or spaced names if URL-encoded).

Success: 200

Example response

{
  "name": "Linux_Router_HOWTO",
  "markdown": "# Router howto\n...",
  "html": "<h1 id=\"router-howto\">Router howto</h1>..."
}

If the page doesn't exist the endpoint returns 404 and a JSON error object.

POST /api/pages

Create a new page. Requires an authenticated session.

Request body: JSON with the following fields

• name — page base name (string). Use underscores for filenames (e.g. My_Page) or a human-friendly name; the server will sanitize with safe_name().
• content — Markdown source for the page (string). Optional (defaults to empty string).

Headers: Content-Type: application/json

Success: 201 Created

Response example

{ "name": "My_Page" }

Errors:

• 400 — missing name
• 401 — authentication required
• 500 — write failure (filesystem error), response includes detail with an error string

PUT /api/pages/

Update an existing page or create it if missing. Requires an authenticated session.

Request body: JSON

• content — Markdown source (required)

Success: 200 with { "name": "<safe_name>" }

Errors:

• 400 — missing content
• 401 — authentication required
• 500 — write failure

Example (update):

curl -b cookies.txt -H "Content-Type: application/json" -X PUT \
  -d '{"content": "# Updated\nNew content..."}' \
  https://example.org/api/pages/My_Page

DELETE /api/pages/

Delete a page. Requires the user to be logged in and to have admin privileges (is_admin).

Success: 204 No Content (empty body)

Errors:

• 401 — authentication required
• 403 — admin required
• 404 — page not found
• 500 — delete failed

Example:

curl -b cookies.txt -X DELETE https://example.org/api/pages/My_Page

Notes and behavior details

• Page names: the application stores filenames with underscores. The API name parameter is passed through safe_name() which strips suspicious characters and replaces slashes with underscores.
• Time/metadata: the JSON page object returned by GET /api/pages/<name> does not include per-page metadata (last_modified) by default; metadata is available via the site UI and the pages_meta/ files on disk.
• Content rendering: when creating or updating a page the server renders Markdown to HTML (using Python-Markdown or fallback libraries) and writes both markdown and rendered HTML to disk.
• History and diffs: when a page is created or updated (via the web UI or the API), the server records a history entry in pages_meta/<name>.history.json.
• Each history entry contains: ts (epoch seconds), ts_human (UTC timestamp), user, action (create, edit, delete, etc.), summary (optional), and diff (string).
• The diff value, when present, is a unified diff (text) computed from the previous Markdown source to the new Markdown source (similar to diff -u before.md after.md).
• Diffs are plain text and may contain a mix of line endings depending on the content; the UI displays the unified diff in a collapsible <pre> block on the per-article history page (/history/<name>).
• Note: GET /api/pages/<name> does not include history or diffs; to view history use the web UI at /history/<name> or read the pages_meta/<name>.history.json file on disk.
• Authentication: the API relies on the Flask session cookie. There is no token-based auth implemented by default. To automate, use curl -c/-b or a script that handles the login form and preserves the cookie jar.

Troubleshooting

• If you receive 401 while authenticated in the browser, ensure your script sends the same cookie jar or includes the session cookie.
• If you need to perform API operations in CI/CD, consider creating a dedicated account and using the cookie-based login flow, or adapt the code to accept an API token (requires code changes).