REST API хэрхэн бүтээх вэ: загвар, аюулгүй байдал, нийтлэх

REST API бүтээхийн тулд аппынхаа удирдаж буй нөөц-үүдийг (хэрэглэгч, захиалга, цаг захиалга) жагсаан, тус бүрт /orders болон /orders/{id} гэх мэт URL өгөөд, үйлдлүүдэд HTTP арга ашиглана: GET уншихад, POST үүсгэхэд, PATCH шинэчлэхэд, DELETE устгахад. Утга учиртай статус код бүхий JSON буцааж, оролт бүрийг баталгаажуулж, серверт нэвтрэлт болон бүртгэл бүрт эрх шалгалт хийж, жагсаалтуудыг хуудаслаарай. Дараа нь эндпоинтуудаа баримтжуулж, API-гаа HTTPS-ийн ард нийтлээрэй.

Энэ гарын авлага загварлах шийдвэрүүд, жишиг маршрутуудын багц, AI аппын бүтээгчид өгөх зааврууд, аюулгүй байдлын алдаа үүсгэдэг буруу алхмуудыг хамруулна. API гэж юу болохыг анх удаа сонирхож байвал эхлээд API гэж юу вэ гэдгийг уншаарай.

REST API хэрэгтэй үед

• Таны веб фронтенд серверт өгөгдөл хадгалах, ачаалах шаардлагатай байх үед
• Мобайл апп, хамтрагч эсвэл автоматжуулалтын хэрэгсэлд таны өгөгдөлд хандах хэрэгтэй байх үед
• Бусад сервисүүд танд үйл явдлын мэдээлэл илгээх үед (webhook)
• Фронтенд болон backend-ийн ажлыг хоёр багт хуваасан үед

REST бол хамгийн түгээмэл загвар боловч цорын ганц нь биш. REST болон GraphQL нь нэг уян хатан асуулгын эндпоинт хаана илүү тохирохыг тайлбарласан.

Эхлээд загварла: нөөц ба маршрут

Аппдаа байгаа нэр үгсийг, мөн хүмүүс тэдгээртэй юу хийдгийг бичиж ав. Энгийн захиалгын аппын жишээ:

Эдгээр нь create, read, update, delete (CRUD) үйлдлүүдтэй таарна; 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. Нөөц ба маршрутуудыг жагсаа дээрхийн дагуу, мөн тус бүрийг хэн дуудаж болохыг оруулаад.
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-оор хязгаарла. Алдааг серверт бүртгэж, 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 жорд эхлэх зааврын жишээ байна: фреймворк болон маршрутаа нэрлэж, алдаанд тодорхой JSON хүс, нууц мэдээллийг орчны хувьсагчид хадгал, Dockerfile оруул. Node, Python, C#, Java болон бусад container backend-ууд Dockerfile-аар нийтлэгдэж, Mythex Publish-ээс deploy-ийг хийнэ (API backends). Төсөл нэгэн зэрэг вебсайт болон API сервертэй байж болох бөгөөд preview дотор хооронд нь шилжиж болно. Нууц мэдээллээ төслийн нууц болгон хадгал, API-д өгөгдлийн сан хэрэгтэй бол чатаар хүс. API-ийнхээ орчмын хуваарьт ажлын хувьд фоны ажлыг хэрхэн ажиллуулах вэ гэдгийг үзнэ үү.

Асуултууд