JSON як формат прийнятний будь-який, але непослідовність у межах API змушує клієнтів писати виняток на кожен ендпойнт. Домовленості варто прийняти заздалегідь і дотримуватися всюди.
1. Стиль ключів - один на весь API: snake_case (природний для Laravel і баз даних) або camelCase (природний для JavaScript). Головне - не змішувати: created_at в одній відповіді й updatedAt в іншій.
2. Дати й час - ISO 8601 / RFC 3339 з часовим поясом:
{ "created_at": "2026-10-04T10:15:00+03:00", "paid_at": "2026-10-04T07:15:00Z" }
Не "04.10.2026", не мітка часу без пояснення, не локальний час без зміщення. «Дата без часу» (день народження) - окремий формат "2026-10-04".
3. Гроші - не числа з рухомою комою: мінімальні одиниці цілим числом ("amount": 125050 копійок) або рядок ("125.50") плюс явна валюта.
4. Ідентифікатори - рядки, якщо можуть бути великими: числа понад 2^53 JavaScript округлює. Для BIGINT чи Snowflake-ID безпечніше "id": "9007199254740993".
5. null чи відсутнє поле: вирішити й задокументувати. Поширений підхід - поле завжди є, null означає «немає значення». Відсутність поля - лише для свідомо необов'язкових чи прихованих правами.
6. Обгортка відповіді: { "data": ..., "meta": ..., "links": ... } для колекцій (пагінація в meta) - так роблять ресурси Laravel. Обгортка дає місце для метаданих без зміни структури даних.
7. Енуми - рядки, а не числа: "status": "paid" читається й не ламається при зміні порядку значень.
8. Булеві значення - true/false, а не 1/0 чи "yes".
9. Помилки - єдиний формат для всіх ендпойнтів (наприклад, Problem Details).
10. Без «магічних» значень: -1 замість null, порожній рядок замість відсутності.
Технічні деталі JSON:
- кодування - UTF-8 (вимога RFC 8259 для обміну між системами);
- порядок ключів в об'єкті не гарантується - клієнт не повинен на нього покладатися;
- дублікати ключів - невизначена поведінка, різні парсери обирають різне значення.
У Laravel: касти дат у моделях ('paid_at' => 'datetime') серіалізуються в ISO 8601 UTC, API Resources керують ключами й форматом явно.
