Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Які домовленості щодо формату JSON варто прийняти в API?

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 керують ключами й форматом явно.

Докладніше в документації: RFC 8259: формат JSON

Перевір себе

20 випадкових питань за спробу, після завершення - розбір кожної помилки

Схожі питання