Jakou strukturu má mít odpověď API

Stručně: výsledky vyjadřujte stavovými kódy 4xx/5xx, payload nesе v { "data": ..., "meta": ... } a při selhání přepněte na obálku error; to stačí pro interní API a jen veřejné platformy s mnoha integrátory potřebují JSON:API nebo OpenAPI.

Nejprve vylučte nejhorší volbu: vždy vracet 200 s výsledkem v poli code.

Tři tvary

A. Samotný objekt

复制{ "id": 1, "name": "demo", "price": 99 }

Čisté a HTTP sémantika dělá práci (404 je 404). Jakmile ale potřebujete stránkování, varování nebo trace id, není kam je dát, aniž byste změnili smlouvu.

B. Stabilní obálka

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "abc", "took": 12 }
}

Payload a metadata žijí odděleně, takže nová metadata nikdy nepřetvoří data. Stojí jednu úroveň vnoření.

C. Obálka na všechno (vyhněte se)

复制{ "code": 0, "message": "success", "data": {...} }

Tvar není hřích; praxe je. Status 200 pro každý výsledek znamená, že CDN, brány, jističe, zásady opakování i dashboardy vidí úspěch. Každý alert pak potřebuje vlastní parsování.

Doporučení

HTTP status pro výsledek, obálka pro payload.

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "req_8f2a", "took": 12 }
}

复制{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Objednávka neexistuje nebo byla smazána",
    "details": [{ "field": "id", "issue": "not_found" }]
  },
  "meta": { "requestId": "req_8f2a" }
}

Status 4xx nebo 5xx; code stabilní a strojově čitelný; message pro lidi; details pro chyby formuláře na úrovni polí.

Tvrdá pravidla

1. Seznamové endpointy musí nést metadata stránkování. Bez total nebo kurzoru není pager.
2. Prázdné seznamy vracejí [], nikdy null. null.map je opakující se výpadek.
3. Časová razítka v ISO 8601 s offsetem. Viz jaký formát pro časová razítka.
4. Jedna konvence pojmenování. snake_case nebo camelCase, převedené jednou na hranici.
5. Peníze jako celé číslo v nejmenších jednotkách nebo jako řetězce. 99.99 není v binární plovoucí desetinné čárce přesné.
6. Nezaměňujte null s chybějícím polem. Viz null, nebo pole vynechat.

Kdy přijmout specifikaci

• Veřejné platformy s mnoha integrátory: JSON:API nebo OpenAPI plus sdílená obálka
• Interní API jednoho týmu: uvedená obálka stačí
• Silné kontrakty: Schema první, struktury generované z něj

Specifikace ušetří diskusi a stojí zaškolení. Pro pětičlenný tým je JSON:API obvykle práce se záporným výsledkem.

Časté dotazy

Jak volit mezi samotným objektem a obálkou?

Obálku použijte, když potřebujete stránkování, varování nebo requestId, aby meta mohla růst bez přetvoření data. Samotný objekt vracejte jen tehdy, když nepotřebujete žádná metadata a můžete přijmout, že pozdější přidání polí změní smlouvu.

Proč by API nemělo vracet 200 pro každý výsledek?

CDN, brány, jističe, zásady opakování i dashboardy čtou HTTP status, aby rozhodly, zda cachovat, opakovat nebo alertovat. S 200 všude považují selhání za úspěch a každý alert potřebuje vlastní parsování obchodního kódu.

Mají seznamové endpointy nést metadata stránkování?

Ano. Bez total nebo kurzoru není pager a prázdné seznamy musí vracet [], nikoli null, jinak volání .map na frontendu selže.

Další čtení

• null, nebo pole vynechat
• Jaký formát pro časová razítka