CoolCMS API

Attributes

#[Info]

$version: '1.0.0'

$title: 'CoolCMS API'

$description: <<<'MD' Veřejné API CoolCMS pro mobilní aplikace a partnery (3. strany). ## Autentizace Dvě hlavičky, které jdou **spolu**: - **apiKeyAuth** — `X-API-Key: <klíč aplikace>` je **povinný u každého požadavku** (jen přes HTTPS). Říká jen „tahle aplikace smí Api volat". Chybějící, neplatný, vypnutý i zrušený klíč dostane stejnou odpověď **401** (`code` 501). Bez klíče jsou jen zpětná volání platebních bran, SMS agregátoru a OAuth poskytovatele. - **bearerAuth** — `Authorization: Bearer <JWT>` volitelně: přihlášený uživatel. Co volání smí, určují role uživatele (bez tokenu role hosta), omezené rolemi, které aplikace smí používat. Každá aplikace má vlastní limity (za sekundu a za minutu) a pod nimi limit na jednoho uživatele / adresu; překročení = **429** s hlavičkou `Retry-After`. Access token (JWT) má krátkou životnost (15 min); obnovuje se přes `/api/system/auth/refresh` rotujícím refresh tokenem. ## Tvar odpovědi Vše je zabalené do obálky `Result` (`{success, message, exception, data, code}`). Užitečná data jsou v `data`; `code` je `ResultCode` (viz dev dokumentace). ## CRUD endpointy Většina modulů má generické CRUD akce odvozené ze sdílených traitů (`get`, `get-all`, `get-by`, `save`, `delete`). Vzor je popsaný u tagu **CRUD (vzor)**; konkrétní zdroje sdílejí stejný kontrakt, liší se jen cestou `api/<modul>/<presenter-kebab>/<akce>`. MD

$contact: new \OpenApi\Attributes\Contact(name: 'CoolSoft', url: 'https://cms.dev.coolsoft.cz')

#[OpenApi]

$security: [['apiKeyAuth' => [], 'bearerAuth' => []], ['apiKeyAuth' => []]]

#[SecurityScheme]

$securityScheme: 'bearerAuth'

$type: 'http'

$scheme: 'bearer'

$bearerFormat: 'JWT'

$description: 'JWT access token získaný z /api/system/auth/login nebo /refresh.'

#[SecurityScheme]

$securityScheme: 'apiKeyAuth'

$type: 'apiKey'

$in: 'header'

$name: 'X-API-Key'

$description: 'Klíč aplikace vydaný v administraci. Povinný u každého požadavku; sám uživatele neurčuje.'

#[Server]

$url: '/'

$description: 'Stejný host jako tato dokumentace'

#[Tag]

$name: 'Auth'

$description: 'Přihlášení, tokeny, profil, odhlášení.'

#[Tag]

$name: 'CRUD (vzor)'

$description: 'Generické CRUD akce sdílené napříč moduly přes traity.'