REST API құру: дизайн, қауіпсіздік және жариялау

REST API құру үшін қолданбаңыз басқаратын ресурстарды (пайдаланушылар, тапсырыстар, брондаулар) тізіп шығыңыз, әрқайсысына /orders және /orders/{id} сияқты URL беріңіз, ал әрекеттер үшін HTTP әдістерін пайдаланыңыз: оқу үшін GET, жасау үшін POST, жаңарту үшін PATCH, жою үшін DELETE. Мағыналы статус кодтары бар JSON қайтарыңыз, әрбір енгізілген деректерді валидациялаңыз, серверде аутентификацияны және әрбір жазбаға құқықты тексеруді талап етіңіз, тізімдерді беттеңіз. Содан кейін эндпоинттерді құжаттаңыз және API-ді HTTPS арқылы жариялаңыз.

Бұл нұсқаулық дизайн шешімдерін, маршруттардың нақты жиынын, AI қолданба құрастырушысына арналған промпттарды және қауіпсіздік тесігіне әкелетін қателерді қарастырады. API-ге жаңа болсаңыз, API дегеніміз не деген мақаладан бастаңыз.

REST API қашан керек

• Веб-фронтендіңізге деректерді серверге сақтап, одан жүктеу керек
• Мобильді қолданбаға, серіктеске немесе автоматтандыру құралына деректеріңізге қол жеткізу керек
• Басқа қызметтер сізге оқиғаларды жібереді (webhook-тар)
• Жұмысты фронтенд және бэкенд командаларына бөлесіз

REST — ең көп таралған стиль, бірақ жалғыз емес. REST пен GraphQL мақаласы бір ғана икемді сұрау эндпоинті қай кезде жақсырақ екенін түсіндіреді.

Алдымен дизайн: ресурстар мен маршруттар

Қолданбаңыздағы зат есімдерді және адамдардың олармен не істейтінін жазып алыңыз. Қарапайым брондау қолданбасы үшін:

Бұлар жасау, оқу, жаңарту және жою (CRUD) әрекеттеріне сәйкес келеді; қараңыз: 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. Деректерді біздің дерекқорда сақтаңыз. Сұрау денелерін схема кітапханасымен валидациялаңыз және белгісіз өрістерді қабылдамаңыз. Қателерді {"error": {"code", "message"}} түрінде, дұрыс статус кодтарымен (400, 401, 403, 404, 409) қайтарыңыз. Құпияларды орта айнымалыларында сақтаңыз.

Қауіпсіздік:

Брондау маршруттарының барлығына кіруді талап етіңіз. Әрбір оқу, жаңарту және жою сұранысында брондаудың ағымдағы пайдаланушыға тиесілі екенін серверде тексеріңіз; тиесілі болмаса 404 қайтарыңыз. Сұрау денесінен пайдаланушы ID-ін немесе рөлдерді ешқашан қабылдамаңыз. POST /api/bookings сұрауын пайдаланушыға минутына 20-мен шектеңіз. Қателерді серверде логтаңыз, стек трейстерін қайтармаңыз.

Құжаттама:

Осы маршруттардың OpenAPI сипаттамасын жазыңыз және әрбір маршрут үшін мысал сұраулар мен жауаптары бар қысқа README жасаңыз.

API-ді тестілеу

Фронтенд сыртынан тестілеңіз, себебі шабуылдаушылар солай істейді:

• Әрбір маршрут дұрыс енгізілгенде жұмыс істейді және құжатталған пішім мен кодты қайтарады
• Жоқ немесе жарамсыз өрістер түсінікті хабармен 400 қайтарады
• Токенсіз әрбір қорғалған маршрут 401 қайтарады
• A пайдаланушысы B пайдаланушысының жазбасын ID арқылы сұраса, 404 немесе 403 алады
• Тізімдер беттелген; өте үлкен limit шектелген
• Қайталанған немесе қайшылықты жасау сұрауы 500 емес, 409 қайтарады
• Сұрау шегі 429 қайтарады
• Қате жауаптарында стек трейстері, SQL немесе құпиялар жоқ
• CORS тек сіз қалаған домендерге рұқсат береді

Жиі кездесетін қателер

• Кіруді тексеріп, иелікті тексермеу. API-дегі ең көп таралған тесік: кез келген кірген пайдаланушы ID-ді өзгертіп, кез келген жазбаны оқи алады.
• Клиентке сену. Сұрау денесіндегі бағалар, рөлдер және пайдаланушы ID-лері өзгертілуі мүмкін.
• Дерекқор жолдарының толығын қайтару. Құпия сөздердің хэштері мен ішкі өрістер ағып кетеді. Әр жауапта нені қосу керегін таңдаңыз.
• Шектелмеген тізімдер. Барлық жазбаны бір сұраумен алу бүкіл қолданбаны баяулатуы мүмкін.
• Ішінде қатесі бар 200 OK. Клиенттер мен мониторинг оның сәтсіз болғанын білмейді.
• Барлығына рұқсат беретін CORS cookie пайдаланатын API-де.
• Денсаулық тексерісі немесе логтар жоқ, сондықтан үзілістерді пайдаланушылардан білесіз.

Іске қосар алдындағы кеңірек тексеру үшін қараңыз: AI арқылы жасалған қолданбаларға арналған қауіпсіздік чек-листі.

Mythex-те REST API құру

Mythex-ке API-ді қолданбаңыздың бөлігі ретінде немесе жеке қызмет ретінде сұрай аласыз. Құжаттамадағы REST API backend рецептінде бастапқы промпт бар: фреймворкіңіз бен маршруттарыңызды атаңыз, айқын JSON қателерін сұраңыз, құпияларды орта айнымалыларында сақтаңыз және Dockerfile қосыңыз. Node, Python, C#, Java және басқа тілдердегі контейнерлік backend-тер Dockerfile арқылы жарияланады, ал деплойды Mythex Publish бөлімінен басқарады (API backends). Жоба веб-сайт пен API серверін қатар жүргізе алады, және оларды превью ішінде ауыстыруға болады. Құпияларды жоба құпиялары ретінде сақтаңыз, ал API дерекқорды қажет етсе, оны чатта сұраңыз. API-ге байланысты фондық жұмыстар үшін қараңыз: фондық тапсырмаларды қалай іске қосу керек.

Сұрақтар