API

API

API v2 pod /api/v2 je integrační rozhraní pro důvěryhodné servery, například samostatnou centrální administraci. Používá vydaný integrační klíč a scopes, HTTPS, konečný seznam zdrojů a polí, silné ETagy pro zápis a audit. Klíč se neposílá do JavaScriptu prohlížeče a API nezapíná CORS. Pokrývá obsah (včetně skrytí a opětovného zobrazení publikovaného článku), strukturu, uživatele, překlady, vyprázdnění cache a záznam změn. Přihlášení přes API neexistuje: lidé se přihlašují na webu na /login/.

Integrační klíč neposílejte z prohlížeče. Prohlížeč má volat vlastní aplikační server, který se potom přes ověřené HTTPS připojí ke každému webu WBengine.

Příklad API

curl -H 'Authorization: Bearer <integrační klíč>' \
  https://example.com/api/v2/identity

Klíč vydá administrátor na stránce /integrations/ webu.

Klíče a scopes

Klíč nese scopes, které určují, co smí. Chybějící či neplatný klíč vrací 401; klíč bez potřebného scope dostane 403. Zapisovací cesty kontrolují povolená pole.

Pro diagnostiku nasazení použijte vendor/bin/wbengine.php doctor; příkaz schéma nemění. API v2 se zapíná samostatně v konfiguraci a pro chráněné obsahové operace vyžaduje své databázové tabulky (viz stránka Nasazení). Discovery, capabilities, zdroje, scopes a pravidla souběžných změn popisuje referenční dokumentace WBengine API v2. Viz také centrální administrace.

Skrytí a zobrazení článku

POST /api/v2/articles/{id}/hide skryje zveřejněný článek a POST /api/v2/articles/{id}/unhide ho znovu zobrazí. Obě volání potřebují oprávnění articles:write a publish:write a hlavičku If-Match s ETagem článku a obě lze bezpečně opakovat. Skrytý článek se nezobrazuje: jeho adresa odpovídá 404, jeho položka menu zmizí a není v sitemapě. Seznam článků lze filtrovat přes hidden=0 nebo hidden=1. Změna se zapíše do záznamu změn jako hide a unhide.

Omezení klíče na adresy

Klíč lze vázat na IP adresy nebo rozsahy CIDR, ve formuláři při vydání nebo později na kartě klíče. Takový klíč funguje jen z těchto adres a každý jiný požadavek je odmítnut s ip_not_allowed. Karta klíče ukazuje adresu, ze které byl naposledy použit, což pomáhá najít klíč používaný z nečekaného místa.

Přehled změn a historie

GET /api/v2/changes (oprávnění audit:read) vrací záznam změn od nejnovější s těmito filtry: resource, resource_id, action, source, actor, since, until a outcome=rejected, který vypíše zápisy, které web odmítl, s kódem chyby. Štítky aktérů zapisují klienti a jsou to data, ne důkaz, kdo je kdo. Úplné snímky stránky, položky menu, sekce nebo boxu lze číst a obnovit přes jeho vlastní cestu changes. Viz Logování a audit.

Obrázky

POST /api/v2/images nahraje obrázek PNG, JPEG nebo WebP do 512 KiB jako base64 s jeho mime (oprávnění images:write). Obrázky lze vypsat, číst a smazat s ETagem a oprávněním k zápisu. Soubor potřebuje adresář mimo kořen webu (apiV2.imageDirectory nebo proměnná prostředí WBENGINE_IMAGE_DIR); bez něj web hlásí obrázky jako nedostupné. Kontroluje se struktura a typ souboru, ale není to plný dekodér obrázků ani antivirus, takže to nepoužívejte jako obecné nahrávání souborů. Nahraný obrázek je veřejné médium: na své adrese se podává každému, kdo ji zná, takže nesmí obsahovat nic tajného.

Statistiky

GET /api/v2/analytics/overview (oprávnění analytics:read) bere from a to (YYYY-MM-DD), granularity (day, week, month) a volitelně locale. Vrací součty, řadu, nejzobrazovanější stránky, články a boxy a zobrazení po jazycích. Viz Statistiky.

Předvolby a MCP server

Při vydání klíče formulář nabízí předvolby pro běžná použití: plnou správu pro centrální administraci, redaktora, agenta pro obsah, agenta, který píše jen koncepty, a jen čtení. AI asistent pracuje přes MCP server s takovým klíčem a smí jen to, co klíč dovoluje.