REST API құру: дизайн, қауіпсіздік және жариялау
REST API құру үшін қолданбаңыз басқаратын ресурстарды (пайдаланушылар, тапсырыстар, брондаулар) тізіп шығыңыз, әрқайсысына /orders және /orders/{id} сияқты URL беріңіз, ал әрекеттер үшін HTTP әдістерін пайдаланыңыз: оқу үшін GET, жасау үшін POST, жаңарту үшін PATCH, жою үшін DELETE. Мағыналы статус кодтары бар JSON қайтарыңыз, әрбір енгізілген деректерді валидациялаңыз, серверде аутентификацияны және әрбір жазбаға құқықты тексеруді талап етіңіз, тізімдерді беттеңіз. Содан кейін эндпоинттерді құжаттаңыз және API-ді HTTPS арқылы жариялаңыз.
Бұл нұсқаулық дизайн шешімдерін, маршруттардың жұмыс жиынтығын, Mythex сияқты AI қолданба құрастырғышына арналған сұраныстарды және қауіпсіздік тесіктеріне әкелетін қателерді қамтиды. Егер API-лар сізге жаңа болса, API дегеніміз не деген сұрақтан бастаңыз.
REST API қашан керек
- Веб-фронтендіңізге деректерді серверге сақтап, одан жүктеу керек
- Мобильді қолданбаға, серіктеске немесе автоматтандыру құралына деректеріңізге қол жеткізу керек
- Басқа қызметтер сізге оқиғаларды жібереді (webhook-тар)
- Жұмысты фронтенд және бэкенд командаларына бөлесіз
REST ең кең таралған стиль, бірақ жалғыз емес. REST пен GraphQL бір икемді сұраныс соңғы нүктесі қашан жақсырақ сәйкес келетінін түсіндіреді.
Алдымен дизайн: ресурстар мен маршруттар
Қолданбаңыздағы зат есімдерді және адамдардың олармен не істейтінін жазып алыңыз. Қарапайым брондау қолданбасы үшін:
| Әдіс | Маршрут | Не істейді | Сәтті код |
|---|---|---|---|
GET | /api/bookings | Қоңырау шалушының брондауларын тізеді (беттеумен) | 200 |
POST | /api/bookings | Брондау жасайды | 201 |
GET | /api/bookings/{id} | Бір брондауды алады | 200 |
PATCH | /api/bookings/{id} | Кейбір өрістерді өзгертеді | 200 |
DELETE | /api/bookings/{id} | Брондауды болдырмайды | 204 |
GET | /api/health | Мониторингке арналған денсаулық тексеруі | 200 |
Бұлар жасау, оқу, жаңарту және жою (CRUD) әрекеттеріне сәйкес келеді; қараңыз: CRUD дегеніміз не. Сақтауға тұрарлық ережелер:
- URL-дерде көпше түрдегі зат есімдер, етістіктерсіз:
/bookings,/getBookingsемес. - Иесін түсіндіру үшін тек бір деңгейде ұя салыңыз:
/bookings/{id}/notes. - CRUD емес әрекеттерді ішкі ресурс ретінде беруге болады:
POST /bookings/{id}/cancel— түсініксіз PATCH-тан анығырақ. - Өрістер атауында бірізділік сақтаңыз, мысалы барлық жерде
created_at.
Статус кодтары мен қателер
Клиент мәтінді талдамай-ақ не болғанын білуі үшін стандартты HTTP кодтарын пайдаланыңыз:
| Код | Мағынасы | Қашан қолданылады |
|---|---|---|
| 200 | OK | Сәтті оқу немесе жаңарту |
| 201 | Created | POST арқылы бірдеңе жасалды |
| 204 | No Content | Сәтті, бірақ қайтаратын ештеңе жоқ |
| 400 | Bad Request | Енгізілген деректер валидациядан өтпеді |
| 401 | Unauthorized | Жүйеге кірілмеген немесе токен жарамсыз |
| 403 | Forbidden | Жүйеге кірілген, бірақ рұқсат жоқ |
| 404 | Not Found | Жоқ, немесе қоңырау шалушы оның бар екенін білмеуі керек |
| 409 | Conflict | Қайталану, немесе уақыт бос емес |
| 429 | Too Many Requests | Сұрау шегі асып кетті |
| 500 | Server Error | Сіздің жағыңызда бірдеңе бұзылды |
Қателерді бір бірыңғай JSON түрінде қайтарыңыз, мысалы {"error": {"code": "slot_taken", "message": "Бұл уақыт енді қолжетімді емес."}}, ал жауаптарға ешқашан стек трейстерін немесе дерекқор қателерін қоспаңыз.
Опциялар мен компромисстер
| Шешім | Қарапайым таңдау | Балама |
|---|---|---|
| API қайда орналасады | Веб-фреймворкіңіздегі API маршруттары | Бөлек API қызметі: бірнеше клиент үшін немесе басқа тіл үшін пайдалы |
| Аутентификация | Өз веб-қолданбаңызға арналған сессия cookie-лері | Мобильді қолданбалар мен үшінші тараптар үшін токендер (bearer токендер немесе API кілттері) |
| Беттеу | ?page=2&limit=20 | Курсор арқылы (?after=...), үлкен және өзгеретін тізімдер үшін тұрақтырақ |
| Нұсқалау | Сыртқы пайдаланушылар болмайынша жоқ | Басқалар тәуелді болғаннан кейін жолда /v1/ |
| Құжаттама | Маршруттар тізімі бар README | OpenAPI спецификациясы, оны интерактивті құжаттама мен клиент кодына айналдыруға болады |
Қадамдық нұсқаулық
- Ресурстар мен маршруттарды тізіңіз, жоғарыда көрсетілгендей, кімнің әрбір маршрутқа қоңырау шала алатынын қоса.
- Деректерді модельдеңіз дерекқорыңызда қажетті өрістер мен байланыстармен.
- Алдымен оқу маршруттарын жасаңыз, содан кейін жасау, жаңарту және жою маршруттарын.
- Әрбір жазу сұрауындағы енгізілгенді валидациялаңыз схема кітапханасымен: міндетті өрістер, түрлер, ұзындықтар, рұқсат етілген мәндер. Белгісіз өрістерді қабылдамаңыз.
- Аутентификация қосыңыз, содан кейін әр жазбаға авторизация:
/bookings/42сұрауында тек жүйеге кіргенін емес, брондау 42 қоңырау шалушыға тиесілі екенін тексеру керек. - Әрбір тізімді беттеңіз және бет өлшемін шектеңіз.
- Кіру және ауыр маршруттарға сұрау шегін қойыңыз. Қараңыз: сұрау шегі.
- CORS-ты тек басқа домендегі браузерлер API-ді шақыруы керек болса ғана баптаңыз, және сол домендерді анық тізіңіз. CORS қателерін түзету мақаласы сізге кездесетін қателерді түсіндіреді.
- Әрбір маршрут үшін құжаттама мен тесттер жазыңыз, соның ішінде сәтсіздік жағдайларын да.
- Құпияларды орта айнымалыларында, 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 дерекқор керек болса, оны чатта сұраңыз: әр жобада өз Postgres дерекқоры болуы мүмкін, ол барлық тарифке кіреді. Агент API-ды сіз үшін тестілей алады, ал Pro тарифінде кодты редакторда және терминалда өзіңіз өңдеуге болады, немесе GitHub-пен екі жақты синхрондауда сақтауға болады. API-ға байланысты фондық жұмыстар үшін фондық тапсырмаларды қалай іске қосу керек бөлімін қараңыз.
Сұрақтар
REST API дегеніміз не?
REST API — бағдарламалардың HTTP арқылы қолданбаңыздың деректерімен жұмыс істеу тәсілі. Деректердің әрбір түрі өз URL-і бар ресурс болып табылады, мысалы /orders, ал стандартты әдістер оған әрекет етеді: GET — оқу, POST — жасау, PATCH немесе PUT — жаңарту, DELETE — жою. Деректер әдетте JSON форматында жіберіледі.
REST API-ді қай тілде құру керек?
Сіз немесе командаңыз қолдай алатын нәрсені қолданыңыз. Express немесе Fastify бар Node.js, FastAPI бар Python және C# немесе Java фреймворктары — барлығы жақсы жұмыс істейді. Маршруттар, мәртебе кодтары, валидация және аутентификация ережелері тілден маңыздырақ. Mythex API-ларды Node, Python, Java, C# немесе Dockerfile арқылы веб-сервер ретінде жұмыс істейтін кез келген нәрседе іске қосады, сондықтан өзің білетін тілді таңдай аласың.
REST API-ді қалай қорғауға болады?
Жария емес әрбір маршрутқа аутентификацияны талап етіңіз, әрбір нақты жазбаға қол жеткізуге құқығы бар-жоғын серверде тексеріңіз, барлық енгізілген деректерді валидациялаңыз, HTTPS пайдаланыңыз, сұрауларды шектеңіз және құпияларды орта айнымалыларында сақтаңыз. Клиент жіберген ID-ға немесе рөлге ешқашан сенбеңіз.
REST API үшін бөлек backend қажет пе?
Міндетті емес. Next.js сияқты фреймворктар API маршруттарын беттермен бірге бере алады. Бөлек API қызметі бірнеше клиент (веб, мобильді, серіктестер) пайдаланғанда немесе оған өз тілі мен масштабтауы керек болғанда мағыналы. Mythex-те веб-сайт пен API бір жобада бола алады және бірге жарияланады.