Formát odpovědi#

🔴 Nejdůležitější kapitola celého manuálu. Přečtěte ji, než začnete psát parser.

Dva různé tvary#

Čtení a zápis vracejí jinou strukturu

Čtení nemá pole success. Zápis ho má. Jednotný parser podle success napsat nejde.

Čtení kolekce#

{
  "items": [
    { "id": { "id": 5 } },
    { "id": { "id": 6 } }
  ],
  "totalCount": 42,
  "_references": {
    "App\\UI\\Api\\Blog\\Models\\Entities\\Article": {
      "5": { "id": 5, "title": "…", "category": { "id": { "id": 3 } } },
      "6": { }
    },
    "App\\UI\\Api\\Blog\\Models\\Entities\\Category": {
      "3": { }
    }
  }
}

V items nejsou data, jsou tam odkazy

Skutečné hodnoty jsou v _references, klíčované plným názvem třídy a identifikátorem. Klient musí umět odkaz rozbalit, jinak dostane jen čísla.

Vazby uvnitř _references jsou opět odkazy — rozbalení je rekurzivní.

Klíč u složeného identifikátoru je spojený pomlčkou

Například "3-7".

totalCount je nula, dokud si o něj neřeknete

Pošlete computeTotalCount=1. Nula tedy neznamená „nic se nenašlo“.

Čtení jednoho záznamu#

{
  "data": { "id": { "id": 5 } },
  "_references": { }
}

Nenalezeno vrací prázdné pole, ne chybu

[]

S kódem HTTP 200. Ne 404 a ne success: false.

Zápis#

{
  "success": true,
  "message": null,
  "data": { },
  "code": 0
}

Pořadí klíčů je pevné. code je číselný kód výsledku, nula znamená v pořádku.

Odpověď na uložení je neúplná

Vrací se jen ploché hodnoty uložené entity — bez vnořených kolekcí a bez identifikátorů nově vzniklých potomků. Po zápisu s vazbami si data načtěte znovu s includes.

Obálka chyby nemusí mít všechny čtyři klíče

Některé chybové větve vracejí jen tři. Nespoléhejte na existenci data.

Technické selhání nese jen kód

Když selže databáze nebo interní volání (kódy skupiny technických chyb, např. chyba databáze, neznámá chyba, zápis souboru, chyba nebo timeout interního API), je message prázdný řetězec a rozhoduje code. Podrobnosti o příčině zůstávají v logu serveru. Chyby z validace a obchodních pravidel (špatná hodnota, nepovolený stav, nenalezeno, oprávnění) nesou svou čitelnou zprávu jako dosud. Klient má proto u prázdné zprávy zobrazit vlastní obecný text.

Stránkování#

Žádné odkazy ani kurzory. Jen offset a limit v dotazu a totalCount v odpovědi.

Typ obsahu#

Chyby 404 a 500 vracejí HTML, ne JSON

Neexistující zdroj nebo neošetřená výjimka vrátí chybovou stránku. Parser musí kontrolovat Content-Type, jinak spadne na neplatném JSONu.

Doporučený postup zpracování#

Zkontrolujte Content-Type — není-li JSON, jde o chybu serveru.
Zkontrolujte stavový kód: 400, 401, 403, 429 zpracujte zvlášť. U 401 rozlište kód 501 (klíč aplikace) a 103 (token uživatele), u 429 čekejte Retry-After. 400 je chyba v sestavení požadavku (špatný tvar parametru, nepovolené pole ve filtru) a nese JSON, viz Chybové kódy.
Je-li v odpovědi success, jde o zápis — rozhodujte podle něj a podle code.
Není-li tam, jde o čtení — rozbalte _references.

Nastavení cookies