Како да изградите REST API: дизајн, безбедност и објавување

За да изградите REST API, наведете ги ресурсите што вашата апликација ги управува (корисници, нарачки, резервации), дајте на секој URL како /orders и /orders/{id}, и користете HTTP методи за дејствата: GET за читање, POST за создавање, PATCH за ажурирање, DELETE за бришење. Враќајте JSON со соодветни статусни кодови, валидирајте секој внес, барајте автентикација и проверки за дозвола по запис на серверот и користете пагинација за листите. Потоа документирајте ги крајните точки и објавете го API-то зад HTTPS.

Овој водич ги опфаќа одлуките за дизајн, работен примерок од рути, упатства за AI градител на апликации и грешките што создаваат безбедносни дупки. Ако API-јата ви се нови, започнете со што е API.

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

• Вашиот веб фронтенд треба да зачувува и вчитува податоци од сервер
• Мобилна апликација, партнер или алатка за автоматизација треба пристап до вашите податоци
• Други услуги ви испраќаат настани (webhooks)
• Работата ја делите помеѓу фронтенд и бекенд тим

REST е најчестиот стил, но не е единствениот. REST vs GraphQL објаснува кога една флексибилна крајна точка за барања е подобра.

Прво дизајн: ресурси и рути

Запишете ги именките во вашата апликација и што луѓето прават со нив. За едноставна апликација за резервации:

Овие се совпаѓаат со создавање, читање, ажурирање и бришење; видете што е CRUD. Конвенции што вреди да се следат:

• Множинска именка без глаголи во URL-ата: /bookings, а не /getBookings.
• Вгнездувајте само едно ниво кога тоа ја појаснува сопственоста: /bookings/{id}/notes.
• Дејствата што не се CRUD можат да бидат под-ресурси: POST /bookings/{id}/cancel е појасно од „магичен“ PATCH.
• Конзистентно именување на полињата, како created_at насекаде.

Статусни кодови и грешки

Користете стандардни HTTP кодови за клиентите да знаат што се случило без парсирање на текст:

Враќајте грешки во еден конзистентен JSON облик, на пример {"error": {"code": "slot_taken", "message": "Тој термин повеќе не е достапен."}}, и никогаш не вклучувајте stack trace или грешки од базата во одговорите.

Опции и компромиси

Чекор по чекор

1. Наведете ги ресурсите и рутите како погоре, вклучувајќи кој smee да ги повикува.
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 ако не му припаѓа. Никогаш не прифаќај ID на корисник или улога од телото на барањето. Ограничи POST /api/bookings на 20 по минута по корисник. Логирај ги грешките на серверот без да враќаш stack trace.

Документација:

Напиши OpenAPI опис на овие рути и кратак README со примери на барања и одговори за секоја од нив.

Тестирање на вашиот API

Тестирајте однадвор од фронтендот, бидејќи нападачите ќе го направат тоа:

• Секоја рута работи со валиден внес и враќа документиран облик и код
• Недостасувачки или неважечки полиња враќаат 400 со јасна порака
• Без токен се враќа 401 на секоја заштитена рута
• Корисник A што бара запис на корисник Б по ID добива 404 или 403
• Листите се пагинирани; огромен limit е ограничен
• Дупликати или конфликтни создавања враќаат 409, не 500
• Ограничувањата на барања враќаат 429
• Одговорите за грешки не содржат stack trace, SQL или тајни податоци
• CORS дозволува само изворите што ги сакате

Чести грешки

• Проверка на најава, но не на сопственост. Најчесташката дупка во API: секој најавен корисник може да прочита било кој запис со менување на ID-то.
• Верување на клиентот. Цените, улогите и ID-ата на корисници од телото на барањето може да се уредуваат.
• Враќање цели редови од базата. Хешови на лозинки и внатрешни полиња се протекуваат. Изберете што ќе содржи секој одговор.
• Неограничени листи. Едно барање за секој запис може да го забави целата апликација.
• 200 OK со порака за грешка внатре. Клиентите и мониторингот не можат да разберат дека не успеало.
• CORS поставен да дозволува сè кај API што користи колачиња.
• Нема проверка на состојба или логови, па за прекини дознавате од корисниците.

За поширока проверка пред лансирање, видете листа за безбедност за апликации изградени со AI.

Изградба на REST API во Mythex

Можете да побарате од Mythex API како дел од вашата апликација или како посебна услуга. Рецептот во документацијата REST API бекенд има почетно упатство: наведете ја рамката и рутите, побарајте јасни JSON грешки, чувајте ги тајните податоци во променливи на околината и вклучете Dockerfile. Контејнерски бекенди во Node, Python, C#, Java и други се објавуваат преку Dockerfile, а Mythex го води деплојот од Publish (API бекенди). Проектот може да работи веб-сајт и API сервер една до друга, а можете да се префрлате меѓу нив во прегледот. Чувајте ги клучевите како тајни податоци на проектот, а ако API-то треба база, побарајте ја во разговорот. За закажана работа околу вашиот API, видете како да извршувате задачи во позадина.

Прашања