Як спроєктувати кінцеву точку API з нечіткого запиту: маршрут, дані й помилки

З чого почати

Перш ніж думати про контролер або обробник, дайте відповідь на прості питання:

• Це читання даних чи зміна стану?
• Який ресурс ми створюємо, читаємо або оновлюємо?
• Хто викликає кінцеву точку: браузер, мобільний застосунок, серверний сервіс чи зовнішній клієнт?
• Які дані обов’язкові, а які можуть бути опційними?
• Що робити, якщо вхід неповний, неправильний або суперечливий?

Якщо на цьому етапі відповідей немає, не варто поспішати з кодом. Спочатку треба домовитися про форму кінцевої точки.

Переклад запиту на функцію в кінцеву точку

У нормальному дизайні кінцева точка не виникає з повітря. Її збирають із кількох рішень:

• маршрут показує, який ресурс ви змінюєте;
• HTTP-метод показує намір;
• контракт запиту описує вхід;
• контракт відповіді описує результат;
• перевірка визначає, що є допустимим;
• код статусу показує, як саме завершився запит;
• межа доступу визначає, хто взагалі може це робити.

Саме цей порядок і знімає магію. Замість “зробімо кінцеву точку” ви отримуєте набір рішень, які можна перевірити до коду.

Що треба зафіксувати до коду

1. Маршрут і ресурс

Спочатку назвіть ресурс простою мовою. Наприклад, не “request helper”, а “замовлення”, “профіль”, “рахунок” або “коментар”.

Потім прив’яжіть до нього метод:

• GET для читання;
• POST для створення;
• PATCH для часткового оновлення;
• DELETE для видалення;
• PUT для повної заміни, якщо це справді потрібно.

2. Контракт запиту

Після цього зафіксуйте, що приходить у запиті:

• які поля обов’язкові;
• які поля опційні;
• які типи і формати очікуються;
• що робити з порожніми рядками, null і невідомими полями.

3. Контракт відповіді

Не менш важливо знати, що повернути назад:

• лише підтвердження успіху;
• створений ресурс;
• змінений ресурс;
• окрему структуру помилок;
• мінімальний обсяг даних для клієнта.

4. Перевірка та помилки

Початківець часто думає про перевірку після реалізації, але саме тут кінцева точка або стає передбачуваною, або ні.

• 4xx означає, що в запиті клієнта є проблема.
• 5xx означає, що проблема на боці сервера або залежності.
• Якщо правило можна перевірити до бізнес-логіки, краще робити це рано.

5. Межі доступу

Коли кінцева точка працює з даними користувача або чутливою дією, потрібно окремо вирішити:

• чи потрібна автентифікація;
• чи потрібна авторизація;
• чи є перевірка на рівні ролі або ресурсу;
• чи не відкриває кінцева точка зайвий доступ “для зручності”.

6. Перші тести

Перед кодом варто вже знати перші тести:

• успішний сценарій;
• негативний сценарій із неправильним форматом даних;
• сценарій із відмовою доступу;
• сценарій із відсутнім або порожнім обов’язковим полем.

Ці тести роблять дизайн видимим. Якщо їх складно назвати, кінцеву точку ще не спроєктовано повністю.

Що не вирішувати зараз

Не намагайтеся одразу закрити всі деталі:

• не вибирайте складний формат відповіді, якщо достатньо простого;
• не розширюйте доступ “на майбутнє”;
• не змішуйте кілька бізнес-дій в одну кінцеву точку;
• не переносіть неоднозначність у код замість того, щоб обговорити її.

Добрий дизайн кінцевої точки часто виглядає нудно. І це плюс: нудний контракт легше тестувати, документувати і підтримувати.

Шаблон запиту

Скопіюйте цей запит і вставте його разом із коротким описом функції, списком полів і будь-якими відомими обмеженнями:

Ви допомагаєте спроєктувати кінцеву точку API для реального запиту на функцію.

Контекст:
- Запит на функцію: [встав короткий опис]
- Хто викликає кінцеву точку: [браузер / мобільний застосунок / серверний сервіс / зовнішній клієнт]
- Дія: [читання / створення / оновлення / видалення / інше]
- Дані на вході: [встав список полів]
- Очікуваний результат: [встав список полів]
- Відомі крайні випадки: [встав список або напишіть "немає"]
- Доступ: [потрібен / не потрібен / неясно]

Завдання:
1. Перетворіть запит на конкретний план кінцевої точки: маршрут, метод, ресурс.
2. Опишіть контракт запиту й контракт відповіді.
3. Розділіть правила перевірки, помилки та коди статусу.
4. Вкажіть, де потрібні межі автентифікації та авторизації.
5. Запропонуйте перші 2-3 тести, які треба написати до реалізації.
6. Якщо є кілька дизайнів, коротко порівняйте їх і виберіть один.

Формат відповіді:
- Підсумок кінцевої точки
- Контракт запиту
- Контракт відповіді
- Перевірка та помилки
- Межі доступу
- Перші тести
- Відкриті питання

Коротко

Хороша кінцева точка API починається з ясного контракту, а не з коду. Якщо запит на функцію ще туманний, цей шаблон допоможе перевести його в маршрут, метод, поля, помилки, доступ і тести.