Začínáme

Od nuly k prvnímu požadavku.

1. Získejte klíč aplikace

Požádejte administrátora webu o klíč pro svou aplikaci (coolcms_ a 64 znaků). Založí ji v Nastavení → Aplikace s přístupem k Api a klíč vám předá. Posílá se v hlavičce X-API-Key u každého požadavku, jen přes HTTPS. Bez něj API vrátí 401. Celý klíč se zobrazí jen jednou, uložte si ho. Podrobně Autentizace.

export API_KEY="coolcms_0123…"   # vložte svůj klíč

Už s klíčem samotným uvidíte totéž co anonymní návštěvník webu:

curl "https://vas-web.cz/api/blog/article/get-all?limit=5" -H "X-API-Key: $API_KEY"

2. Přihlaste se

Přihlášení je potřeba, jen když aplikace jedná jménem uživatele. Klíč se posílá i tady.

curl -X POST https://vas-web.cz/api/system/auth/login \
  -H "X-API-Key: $API_KEY" \
  -d "username=vas-ucet" \
  -d "password=vase-heslo"

Tělo musí být formulářové, ne JSON

Přihlašovací endpointy čtou application/x-www-form-urlencoded. JSON tělo nepřečtou a přihlášení selže.

Odpověď:

{
  "success": true,
  "message": null,
  "data": {
    "user": { },
    "token": "<access token>",
    "refreshToken": "<refresh token>",
    "payload": { }
  },
  "code": 0
}

3. Zavolejte první čtení

curl "https://vas-web.cz/api/blog/article/get-all?limit=5&computeTotalCount=1" \
  -H "X-API-Key: $API_KEY" \
  -H "Authorization: Bearer <access token>"

Bez computeTotalCount=1 je totalCount nula

Není to prázdný výsledek, jen se nepočítal.

4. Rozbalte odpověď

Data nejsou v items. V items jsou jen odkazy; skutečné hodnoty jsou v _references. Podrobně Formát odpovědi.

5. Obnovujte token

Přístupový token platí 15 minut. Pak se obnoví:

curl -X POST https://vas-web.cz/api/system/auth/refresh \
  -H "X-API-Key: $API_KEY" \
  -d "refreshToken=<refresh token>"

Vrátí nový pár — starý refresh token přestane platit.

Uložte si nový refresh token, jinak se odhlásíte

Použití starého po obnově vyhodnotí systém jako krádež a zneplatní celou větev.

Checklist před ostrým provozem

• Každý požadavek nese X-API-Key a klíč je na serveru v tajnosti (Autentizace).
• Parametry posíláte v adrese, ne v těle — kromě hesel, ta jdou jen v těle (Autentizace).
• Parser rozlišuje dva tvary odpovědi.
• Kontrolujete success, ne jen kód HTTP.
• Kontrolujete Content-Type — chyby 404 a 500 vracejí HTML.
• Umíte zpracovat 401 kdykoli, ne až po vypršení — rozlišujete kód 501 (klíč) a 103 (token).
• Vaše doména je zapsaná v povolených původech.
• Při 429 čekáte Retry-After sekund; počítáte s limity aplikace, které sdílejí všichni její uživatelé.
• Počítáte s limitem na přihlašovacích endpointech a s kvótou zakládání obsahu.
• Odpověď 400 berete jako chybu sestavení požadavku, ne jako výpadek.
• Počítáte s tím, že osobní údaje cizích uživatelů přijdou prázdné nebo zamaskované.

Volání ze serveru versus z prohlížeče

	Ze serveru	Z prohlížeče
CORS	neplatí	musíte být na seznamu
Klíč aplikace	v hlavičce, tajný	v hlavičce, není tajný (každý ho vytáhne)
Token	v hlavičce	v hlavičce
Retry-After	přečtete	nepřečtete — hlavička není zveřejněná; čtěte data.retryAfter z těla

Nastavení cookies