Як створити REST API: дизайн, безпека та розгортання

Щоб створити REST API, складіть перелік ресурсів, якими керує ваш застосунок (користувачі, замовлення, бронювання), призначте кожному URL на кшталт /orders і /orders/{id} та використовуйте методи HTTP для дій: GET для читання, POST для створення, PATCH для оновлення, DELETE для видалення. Повертайте JSON із зрозумілими кодами статусів, валідуйте кожне вхідне поле, вимагайте автентифікацію та перевірки прав на рівні окремого запису на сервері, а списки розбивайте на сторінки. Далі задокументуйте ендпоінти й розгорніть API за HTTPS.

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

Коли потрібен REST API

• Вашому веб-інтерфейсу потрібно зберігати й завантажувати дані з сервера
• Мобільному застосунку, партнеру або інструменту автоматизації потрібен доступ до ваших даних
• Інші сервіси надсилають вам події (вебхуки)
• Ви розділяєте роботу між командами фронтенду та бекенду

REST — найпоширеніший стиль, але не єдиний. REST проти GraphQL пояснює, коли краще підходить один гнучкий endpoint для запитів.

Спочатку дизайн: ресурси й маршрути

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

Ці маршрути відповідають операціям створення, читання, оновлення та видалення; див. що таке CRUD. Корисні правила:

• Множина в іменниках, без дієслів в URL: /bookings, а не /getBookings.
• Вкладеність лише на один рівень, якщо це прояснює належність: /bookings/{id}/notes.
• Дії, які не є CRUD, можна оформити як підресурси: POST /bookings/{id}/cancel зрозуміліше, ніж прихований PATCH.
• Єдине іменування полів, наприклад created_at скрізь.

Коди статусів і помилки

Використовуйте стандартні коди HTTP, щоб клієнти розуміли результат без розбору тексту:

Повертайте помилки в одній послідовній структурі JSON, наприклад {"error": {"code": "slot_taken", "message": "Цей час більше не доступний."}}, і ніколи не включайте у відповіді стек викликів чи помилки бази даних.

Варіанти та компроміси

Крок за кроком

1. Перелічіть ресурси та маршрути, як показано вище, включно з тим, хто може викликати кожен із них.
2. Змоделюйте дані у базі даних із потрібними полями та зв’язками.
3. Спочатку створіть маршрути читання, потім створення, оновлення та видалення.
4. Валідуйте вхідні дані для кожного запису за допомогою бібліотеки схем: обов’язкові поля, типи, довжина, дозволені значення. Відхиляйте невідомі поля.
5. Додайте автентифікацію, а потім авторизацію для кожного запису: завантаження /bookings/42 має перевіряти, що бронювання 42 належить викликачу, а не лише те, що користувач увійшов.
6. Розбивайте на сторінки кожен список і обмежуйте розмір сторінки.
7. Обмежуйте кількість запитів для входу та ресурсомістких маршрутів. Див. обмеження частоти запитів.
8. Налаштуйте CORS лише тоді, коли браузери на інших доменах мають викликати API, і явно перелічіть ці джерела. Як виправити помилки CORS пояснює помилки, які ви побачите.
9. Напишіть документацію й тести для кожного маршруту, включно з випадками відмови.
10. Розгорніть із секретами в змінних середовища, HTTPS, логами та перевіркою стану.

Промпти для вашого AI-конструктора

Каркас:

Створи REST API для бронювань з такими маршрутами: GET /api/health, GET /api/bookings (з пагінацією, максимум 50 на сторінку), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Зберігай дані в нашій базі даних. Валідуй тіло запитів за допомогою бібліотеки схем і відхиляй невідомі поля. Повертай помилки JSON у форматі {"error": {"code", "message"}} з правильними кодами статусів (400, 401, 403, 404, 409). Зберігай секрети в змінних середовища.

Безпека:

Вимагай вхід для кожного маршруту бронювань. Для кожного читання, оновлення та видалення перевіряй на сервері, що бронювання належить поточному користувачу; якщо ні, повертай 404. Ніколи не приймай ідентифікатори користувачів або ролі з тіла запиту. Обмежуй POST /api/bookings до 20 запитів на хвилину для кожного користувача. Логуй помилки на сервері, не повертаючи стеки викликів.

Документація:

Напиши опис цих маршрутів у форматі OpenAPI та коротке README з прикладами запитів і відповідей для кожного маршруту.

Тестування API

Тестуйте API ззовні фронтенду, адже так діятимуть зловмисники:

• Кожен маршрут працює з коректними даними та повертає задокументовану структуру й код
• Відсутні або некоректні поля повертають 400 з чітким повідомленням
• Відсутність токена повертає 401 на кожному захищеному маршруті
• Користувач A, який запитує запис користувача B за ID, отримує 404 або 403
• Списки розбиті на сторінки, а дуже великий limit обмежується
• Дублікати або конфліктні створення повертають 409, а не 500
• Обмеження частоти повертають 429
• Відповіді з помилками не містять стеків викликів, SQL чи секретів
• CORS дозволяє лише задумані джерела

Типові помилки

• Перевірка входу без перевірки належності. Найпоширеніша діра в API: будь-який увійдений користувач може прочитати будь-який запис, змінивши ID.
• Довіра до клієнта. Ціни, ролі та ID користувачів із тіла запиту можна змінити.
• Повернення цілих рядків бази даних. Хеші паролів і внутрішні поля витікають. Вирішіть, що саме має містити кожна відповідь.
• Необмежені списки. Запит на кожен запис може сповільнити весь застосунок.
• 200 OK із помилкою всередині. Клієнти й моніторинг не зможуть визначити, що запит не вдався.
• CORS, налаштований на дозвіл усього, для API, який використовує cookie.
• Немає перевірки стану чи логів, тож про збої ви дізнаєтеся від користувачів.

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

Створення REST API у Mythex

У Mythex можна попросити API як частину вашого застосунку або як окремий сервіс. У рецепті документації REST API backend є стартовий промпт: назвіть фреймворк і маршрути, попросіть чіткі JSON-помилки, зберігайте секрети в змінних середовища та додайте Dockerfile. Бекенди-контейнери на Node, Python, C#, Java та інших публікуються через Dockerfile, а розгортання з Publish виконує Mythex (API-бекенди). Проєкт може працювати з вебсайтом і сервером API поруч, і ви можете перемикатися між ними в превʼю. Зберігайте ключі як секрети проєкту, а якщо API потребує бази даних, попросіть її в чаті. Для планових завдань навколо вашого API див. як запускати фонові завдання.

Запитання