Как да създадете REST API: дизайн, сигурност и публикуване

За да създадете REST API, изброете ресурсите, които управлява приложението ви (потребители, поръчки, резервации), дайте на всеки URL като /orders и /orders/{id} и използвайте HTTP методи за действията: GET за четене, POST за създаване, PATCH за промяна и DELETE за изтриване. Връщайте JSON със смислени статус кодове, валидирайте всеки входен параметър, изисквайте удостоверяване и проверки на правата за всеки запис на сървъра и странирайте списъците. После документирайте крайните точки и публикувайте API зад HTTPS.

Това ръководство обхваща решенията за дизайн, примерен набор от маршрути, промпти за AI инструмент за създаване на приложения и грешките, които водят до пробиви в сигурността. Ако API са ви нови, започнете с какво е API.

Кога ви трябва REST API

• Уеб интерфейсът ви трябва да записва и зарежда данни от сървър
• Мобилно приложение, партньор или инструмент за автоматизация трябва да има достъп до данните ви
• Други услуги ви изпращат събития (webhooks)
• Работата се разделя между екип за frontend и екип за backend

REST е най-често срещаният стил, но не е единственият. REST срещу GraphQL обяснява кога една гъвкава заявка към един краен адрес е по-подходяща.

Първо дизайн: ресурси и маршрути

Запишете съществителните в приложението си и какво правят хората с тях. За просто приложение за резервации:

Това съответства на създаване, четене, промяна и изтриване; вижте какво е 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-то

Тествайте отвън, от фронтенда, защото атакуващите ще го правят:

• Всеки маршрут работи с валидни данни и връща описаната структура и код
• Липсващи или невалидни полета връщат 400 с ясно съобщение
• Без токен всеки защитен маршрут връща 401
• Потребител A, който заявява запис на потребител B по ID, получава 404 или 403
• Списъците са странирани; голям limit е ограничен
• Дублиращи или конфликтни създавания връщат 409, а не 500
• Лимитите на заявки връщат 429
• Грешките не съдържат стекове, SQL или тайни ключове
• CORS разрешава само източниците, които искате

Чести грешки

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

За по-широка проверка преди пускане вижте контролния списък за сигурност за приложения, създадени с AI.

Създаване на REST API в Mythex

Можете да поискате от Mythex API като част от приложението си или като отделна услуга. Рецептата за документацията REST API backend има стартов промпт: назовете рамката и маршрутите, поискайте ясни JSON грешки, пазете тайните ключове в променливи на средата и включете Dockerfile. Container бекенди на Node, Python, C#, Java и други се публикуват чрез Dockerfile, а Mythex поема публикуването от Publish (API бекенди). Проектът може да работи като уебсайт и API сървър едновременно, а между тях можете да превключвате в преглед. Съхранявайте ключовете като тайни на проекта, а ако API-то има нужда от база данни, поискайте я в чата. За планирана работа около API-то вижте как да стартирате фонови задачи.

Въпроси