REST API хэрхэн бүтээх вэ: загвар, аюулгүй байдал, нийтлэх
REST API бүтээхийн тулд аппынхаа удирдаж буй нөөц-үүдийг (хэрэглэгч, захиалга, цаг захиалга) жагсаан, тус бүрт /orders болон /orders/{id} гэх мэт URL өгөөд, үйлдлүүдэд HTTP арга ашиглана: GET уншихад, POST үүсгэхэд, PATCH шинэчлэхэд, DELETE устгахад. Утга учиртай статус код бүхий JSON буцааж, оролт бүрийг баталгаажуулж, серверт нэвтрэлт болон бүртгэл бүрт эрх шалгалт хийж, жагсаалтуудыг хуудаслаарай. Дараа нь эндпоинтуудаа баримтжуулж, API-гаа HTTPS-ийн ард нийтлээрэй.
Энэ гарын авлага нь дизайны шийдвэр, жишээ route-ууд, AI app builder (Mythex)-т зориулсан prompt, аюулгүй байдлын цоорхой үүсгэдэг алдаануудыг хамруулна. API танд шинэ бол эхлээд API гэж юу вэ-г уншаарай.
REST API хэрэгтэй үед
- Таны веб фронтенд серверт өгөгдөл хадгалах, ачаалах шаардлагатай байх үед
- Мобайл апп, хамтрагч эсвэл автоматжуулалтын хэрэгсэлд таны өгөгдөлд хандах хэрэгтэй байх үед
- Бусад сервисүүд танд үйл явдлын мэдээлэл илгээх үед (webhook)
- Фронтенд болон backend-ийн ажлыг хоёр багт хуваасан үед
REST бол хамгийн түгээмэл загвар боловч цорын ганц биш. REST ба GraphQL нь нэг уян хатан query endpoint хаана илүү таарч байгааг тайлбарлана.
Эхлээд загварла: нөөц ба маршрут
Аппдаа байгаа нэр үгсийг, мөн хүмүүс тэдгээртэй юу хийдгийг бичиж ав. Энгийн захиалгын аппын жишээ:
| Арга | Маршрут | Юу хийдэг | Амжилттай код |
|---|---|---|---|
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 |
Эдгээр нь create, read, update, delete (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": "Тэр цаг одоо боломжгүй байна."}}, мөн хариунд stack trace эсвэл өгөгдлийн сангийн алдааг хэзээ ч бүү оруул.
Сонголт ба ашиг, алдагдал
| Шийдвэр | Энгийн сонголт | Өөр хувилбар |
|---|---|---|
| API хаана байрлах вэ | Веб фреймворкийн API маршрут | Тусдаа API сервис; олон клиент эсвэл өөр хэл хэрэгтэй үед |
| Баталгаажуулалт | Өөрийн веб аппд session cookie | Мобайл апп болон гуравдагч талд bearer токен эсвэл API key |
| Хуудаслалт | ?page=2&limit=20 | Cursor-д суурилсан (?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-оор хязгаарла. Алдааг серверт бүртгэж, stack trace буцаахгүй бай.
Баримт:
Эдгээр маршрутуудын OpenAPI тодорхойлолт, мөн маршрут бүрт жишээ хүсэлт, хариутай богино README бич.
API-гаа тестлэх
Фронтендээс гадуур тестлэ, учир нь халдагчид тэгэх болно:
- Маршрут бүр зөв оролтоор ажиллаж, баримтлагдсан хэлбэр, кодыг буцаадаг
- Дутуу эсвэл буруу талбар нь тодорхой мессежтэй 400 буцаадаг
- Токенгүй байвал хамгаалагдсан маршрут бүр 401 буцаадаг
- Хэрэглэгч А нь хэрэглэгч Б-ийн бүртгэлийг ID-аар авахад 404 эсвэл 403 авдаг
- Жагсаалтууд хуудаслагдсан; асар том
limitхязгаарлагддаг - Давхардсан эсвэл зөрчилтэй үүсгэлт 500 биш, 409 буцаадаг
- Хязгаарлалтын хариу 429 байдаг
- Алдааны хариунд stack trace, SQL эсвэл нууц мэдээлэл байдаггүй
- CORS зөвхөн таны зорьсон эх сурвалжуудыг зөвшөөрдөг
Түгээмэл алдаанууд
- Нэвтрэлтийг шалгаад, эзэмшлийг шалгаагүй. API-ийн хамгийн түгээмэл нүх: нэвтэрсэн ямар ч хэрэглэгч ID-г солиод дурын бүртгэлийг уншиж чадна.
- Клиентэд итгэх. Хүсэлтийн биеэс ирсэн үнэ, эрх, хэрэглэгчийн ID засагдаж болно.
- Өгөгдлийн сангийн бүх мөрийг буцаах. Нууц үгийн hash болон дотоод талбарууд задарна. Хариунд юу орохыг сонго.
- Хязгааргүй жагсаалт. Бүх бүртгэлийг нэг хүсэлтээр авах нь бүх аппыг удаашруулж болно.
- Алдааны мессежтэй
200 OK. Клиент болон мониторинг алдаа гарснаа мэдэхгүй. - Бүгдийг зөвшөөрдөг CORS cookie ашигладаг API дээр.
- Эрүүл мэндийн шалгалт эсвэл лог байхгүй, тийм учраас унтралтыг хэрэглэгчдээс сонсдог.
Нийтлэхийн өмнөх илүү өргөн шалгалтад AI-аар бүтээсэн аппын аюулгүй байдлын жагсаалт тусална.
Mythex дээр REST API бүтээх нь
Mythex-ээс API-г аппынхаа нэг хэсэг эсвэл тусдаа үйлчилгээ болгож асууж болно. Docs-ийн REST API backend жор нь эхлэх prompt-тай: framework болон route-уудаа нэрлэ, тодорхой JSON алдаа асуу, нууцуудаа орчны хувьсагчид хадгал, Dockerfile оруул. Node, Python, C#, Java болон бусад container backend-үүд Dockerfile-аар нийтлэгдэж, Publish-аас Mythex deploy-ийг хариуцна (API backends). Төсөл вэбсайт болон API серверийг зэрэгцүүлэн ажиллуулж, preview дээр хооронд нь сольж болно. Нууцуудыг төслийн нууц болгон хадгал; 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 framework-үүд сайн ажилладаг. Route, status code, баталгаажуулалт, нэвтрэлтийн дүрмүүд хэлнээс илүү чухал. Mythex нь Node, Python, Java, C#, эсвэл Dockerfile-аас веб сервер болж ажилладаг аливаа зүйлээр API ажиллуулдаг тул таны мэддэг хэлийг сонгоно.
REST API-г хэрхэн хамгаалах вэ?
Нийтэд нээлттэй биш бүх маршрутад нэвтрэлт шаардаж, бүх оролтыг баталгаажуулж, тухайн бүртгэлд хандах эрхийг серверт шалгаж, HTTPS ашиглаж, хүсэлтийн тоог хязгаарлаж, нууц мэдээллээ орчны хувьсагчид хадгалаарай. Клиентээс ирсэн ID эсвэл эрхийн төрлийг хэзээ ч бүү итгэ.
REST API-д тусдаа backend хэрэгтэй юу?
Үргэлж биш. Next.js зэрэг framework нь хуудсын хажууд API route-уудыг үйлчилж чадна. Тусдаа API сервис нь хэд хэдэн клиент (вэб, утас, түнш) ашигладаг үед, эсвэл өөрийн хэл, масштабтай байх шаардлагатай үед утга учиртай. Mythex-д вэбсайт болон API нэг төсөлд байж, хамт нийтлэгдэж болно.