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,
  "exception": 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šech pět klíčů

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

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í

1. Zkontrolujte Content-Type — není-li JSON, jde o chybu serveru.
2. Zkontrolujte stavový kód: 401, 403, 429 zpracujte zvlášť.
3. Je-li v odpovědi success, jde o zápis — rozhodujte podle něj a podle code.
4. Není-li tam, jde o čtení — rozbalte _references.