Нұсқаулықтар

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 кодтарын пайдаланыңыз:

КодМағынасыҚашан қолданылады
200OKСәтті оқу немесе жаңарту
201CreatedPOST арқылы бірдеңе жасалды
204No ContentСәтті, бірақ қайтаратын ештеңе жоқ
400Bad RequestЕнгізілген деректер валидациядан өтпеді
401UnauthorizedЖүйеге кірілмеген немесе токен жарамсыз
403ForbiddenЖүйеге кірілген, бірақ рұқсат жоқ
404Not FoundЖоқ, немесе қоңырау шалушы оның бар екенін білмеуі керек
409ConflictҚайталану, немесе уақыт бос емес
429Too Many RequestsСұрау шегі асып кетті
500Server ErrorСіздің жағыңызда бірдеңе бұзылды

Қателерді бір бірыңғай JSON түрінде қайтарыңыз, мысалы {"error": {"code": "slot_taken", "message": "Бұл уақыт енді қолжетімді емес."}}, ал жауаптарға ешқашан стек трейстерін немесе дерекқор қателерін қоспаңыз.

Опциялар мен компромисстер

ШешімҚарапайым таңдауБалама
API қайда орналасадыВеб-фреймворкіңіздегі API маршруттарыБөлек API қызметі: бірнеше клиент үшін немесе басқа тіл үшін пайдалы
АутентификацияӨз веб-қолданбаңызға арналған сессия cookie-леріМобильді қолданбалар мен үшінші тараптар үшін токендер (bearer токендер немесе API кілттері)
Беттеу?page=2&limit=20Курсор арқылы (?after=...), үлкен және өзгеретін тізімдер үшін тұрақтырақ
НұсқалауСыртқы пайдаланушылар болмайынша жоқБасқалар тәуелді болғаннан кейін жолда /v1/
ҚұжаттамаМаршруттар тізімі бар READMEOpenAPI спецификациясы, оны интерактивті құжаттама мен клиент кодына айналдыруға болады

Қадамдық нұсқаулық

  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 дерекқор керек болса, оны чатта сұраңыз: әр жобада өз 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 бір жобада бола алады және бірге жарияланады.

Mythex · Pricing · ЖИ көмегімен кез келген нәрсені жасаңыз · Сайттар мен қосымшаларға арналған үлгілер · Mythex салыстыруда · ЖИ-мен қосымша жасау сөздігі · ЖИ-мен қосымша жасауға арналған тегін құралдар · English

English አማርኛ العربية Български বাংলা Bosanski Català Čeština Dansk Deutsch Ελληνικά Español Español (España) Eesti فارسی Suomi Français Français (Canada) ગુજરાતી हिन्दी Hrvatski Magyar Հայերեն Bahasa Indonesia Íslenska Italiano 日本語 ქართული ಕನ್ನಡ 한국어 Lietuvių Latviešu Македонски മലയാളം Монгол मराठी Bahasa Melayu မြန်မာ Norsk bokmål Nederlands ਪੰਜਾਬੀ Polski Português (Brasil) Português (Portugal) Română Русский Slovenčina Slovenščina Soomaali Shqip Srpski Svenska Kiswahili தமிழ் తెలుగు ไทย Tagalog Türkçe Українська اردو Tiếng Việt 简体中文 繁體中文(香港) 繁體中文(台灣)