API pro partnery#
REST rozhraní CoolCMS. Slouží mobilním aplikacím, partnerským systémům a vlastním klientům.
Kde začít#
- Začínáme — první požadavek za pět minut. Nejdřív potřebujete klíč aplikace.
- Autentizace — klíč aplikace a token uživatele.
- Formát odpovědi — 🔴 přečtěte, než začnete psát parser.
- CRUD vzor — čtení a zápis.
- Chybové kódy.
Tvar adresy#
Volitelně s jazykovým prefixem: /en/api/…. Výchozí jazyk je čeština.
Moduly a jejich zdroje jsou v referenci.
Každý požadavek nese hlavičku X-API-Key s klíčem aplikace, který vám vydá administrátor
webu. Bez ní API vrátí 401. Přihlášený uživatel se přidává tokenem v hlavičce Authorization.
Viz Autentizace.
🔴 Tři věci, které překvapí každého#
Přečtěte je teď, ať je nemusíte hledat v ladicím nástroji.
1. Parametry se posílají v adrese, ne v těle požadavku
I u zápisu. POST s JSON tělem projde jako „chybí data“. Výjimkou jsou
přihlašovací endpointy, které naopak čtou formulářové tělo, a akce s hesly, které
je čtou jen z těla. Podrobně CRUD vzor.
2. Čtení a zápis mají různý tvar odpovědi
Čtení vrací items a _references bez pole success. Zápis vrací obálku
s success. Jednotný parser podle success napsat nejde. Podrobně
Formát odpovědi.
3. Chyby chodí s kódem HTTP 200
Validace dat, „nenalezeno“ i konflikt. Stavový kód rozliší jen 400 (špatně sestavený požadavek), 401, 403, 429 a 204. Podrobně Chybové kódy.
Co API umí#
| Skupina | Akce |
|---|---|
| Čtení | get, get-by, get-all |
| Zápis | save, update-columns |
| Mazání | delete, delete-all |
| Strom | move-up, move-down, move-subtree, delete-node |
| Události | register-event |
Specifikace#
Strojová specifikace je na /api-docs.json, prohlížeč na /api-docs/. U každé operace
vyžaduje schéma apiKeyAuth (klíč aplikace) a volitelně bearerAuth (token uživatele).
Specifikace pokrývá zatím jen přihlašovací endpointy
Pět cest (přihlášení, obnova, odhlášení, profil a ověření tokenu) z několika stovek. Zbytek popisuje tenhle manuál. Nespoléhejte na generovaného klienta.