REST API እንዴት እንደሚገነቡ፡ ዲዛይን፣ ደህንነት እና ማሰማራት
REST API ለመገንባት፣ መተግበሪያዎ የሚያስተዳድራቸውን ግብዓቶች (ለምሳሌ ተጠቃሚዎች፣ ትዕዛዞች፣ ቦታ ማስያዣዎች) ይዘርዝሩ፤ እያንዳንዳቸውን እንደ /orders እና /orders/{id} ያለ URL ይስጡ፤ ለድርጊቶች HTTP ዘዴዎችን ይጠቀሙ፦ GET ለማንበብ፣ POST ለመፍጠር፣ PATCH ለማዘመን፣ DELETE ለመሰረዝ። ትክክለኛ የሁኔታ ኮዶች ያለው JSON ይመልሱ፣ እያንዳንዱን ግብዓት ያረጋግጡ፣ ማረጋገጫ እና በእያንዳንዱ መዝገብ ላይ የፈቃድ ፍተሻ በሰርቨሩ ላይ ይጠይቁ፣ ዝርዝሮችንም በገጾች ይከፋፍሉ። ከዚያ ኤፒአይ ነጥቦቹን ይመዝግቡ እና ኤፒአይውን ከHTTPS ጀርባ ያሰማሩ።
ይህ መመሪያ የዲዛይን ውሳኔዎችን፣ የተሰሩ መንገዶችን፣ ለAI መተግበሪያ ገንቢ የሚሰጡ ጥያቄዎችን እና ወደ ደህንነት ክፍተት የሚመሩ ስህተቶችን ይሸፍናል። ኤፒአይ አዲስ ከሆነብዎ፣ ኤፒአይ ምንድን ነው በሚለው ይጀምሩ።
REST API መቼ ያስፈልግዎታል
- የድር ፍሮንትኤንድዎ ዳታን ከሰርቨር ማስቀመጥ እና መጫን ሲፈልግ
- የሞባይል መተግበሪያ፣ አጋር ወይም አውቶሜሽን መሳሪያ ወደ ዳታዎ መድረስ ሲፈልግ
- ሌሎች አገልግሎቶች ክስተቶችን ወደ እርስዎ ሲልኩ (ዌብሁክስ)
- ስራን በፍሮንትኤንድ እና በባክኤንድ ቡድኖች መካከል ሲከፋፍሉ
REST በጣም የተለመደ ዘይቤ ነው፤ ብቸኛው ግን አይደለም። REST vs 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": "ያ ሰዓት ከአሁን በኋላ አይገኝም።"}}፤ እና የስታክ ትሬስ ወይም የዳታቤዝ ስህተቶችን በምላሾች ውስጥ ፈጽሞ አታካትቱ።
አማራጮች እና ለውጦች
| ውሳኔ | ቀላሉ ምርጫ | አማራጭ |
|---|---|---|
| ኤፒአይው የሚኖርበት ቦታ | በድር ፍሬምወርክዎ ውስጥ ያሉ የኤፒአይ መንገዶች | ለብዙ ደንበኞች ወይም ለተለየ ቋንቋ የሚጠቅም የተለየ የኤፒአይ አገልግሎት |
| ማረጋገጫ | ለራስዎ ድር መተግበሪያ የሴሽን ኩኪዎች | ለሞባይል መተግበሪያዎች እና ለሶስተኛ ወገኖች ቶከኖች (bearer tokens ወይም API keys) |
| ገጽ መከፈል | ?page=2&limit=20 | ለትልልቅ እና ለሚቀያየሩ ዝርዝሮች የበለጠ የተረጋጋ በጠቋሚ ላይ የተመሰረተ (?after=...) |
| ቨርዥን | ሰዎች ውጭ ተጠቃሚ እስኪኖሮት ድረስ የለም | ሌሎች ሲመኩበት በመንገዱ ውስጥ /v1/ |
| ሰነዶች | መንገዶችን የሚዘረዝር README | መሳሪያዎች ወደ በይነተገናኝ ሰነድ እና ወደ ደንበኛ ኮድ የሚቀይሩት OpenAPI ስፔክ |
በደረጃ
- ግብዓቶችን እና መንገዶችን ዘርዝሩ ከላይ እንደተባለው፣ ማን እያንዳንዱን ሊጠራ እንደሚችል ጨምሮ።
- ዳታውን ሞዴል ያድርጉ በዳታቤዝዎ ውስጥ በሚፈልጓቸው መስኮች እና ግንኙነቶች።
- የንባብ መንገዶችን መጀመሪያ ይገንቡ፣ ከዚያ ፍጠር፣ አዘምን እና ሰርዝ።
- ግብዓትን በእያንዳንዱ ጽሑፍ ላይ ያረጋግጡ በስኪማ ላይብረሪ፦ የሚፈለጉ መስኮች፣ ዓይነቶች፣ ርዝመቶች፣ የተፈቀዱ እሴቶች። ያልታወቁ መስኮችን ውድቅ ያድርጉ።
- ማረጋገጫ ይጨምሩ፣ ከዚያ በመዝገብ ደረጃ ፈቃድ፦
/bookings/42መጫን የቦታ ማስያዣ 42 የጠሪው መሆኑን ማረጋገጥ አለበት፣ ዝም ብሎ አንድ ሰው መግባቱን ብቻ ሳይሆን። - እያንዳንዱን ዝርዝር በገጽ ይከፋፍሉ እና የገጽ መጠኑን ይገድቡ።
- የመግቢያ እና ውድ መንገዶችን ይገድቡ። የጥያቄ ገደብ ይመልከቱ።
- CORS ያዋቅሩ የሚሆነው ሌሎች ዶሜኖች ያሉ ብራውዘሮች ኤፒአዩን መጥራት ካለባቸው ብቻ ነው፤ እነዚያንም ምንጮች በግልጽ ይዘርዝሩ። የ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። ዳታውን በዳታቤዛችን ውስጥ ያስቀምጡ። የጥያቄ አካላትን በስኪማ ላይብረሪ ያረጋግጡ እና ያልታወቁ መስኮችን ውድቅ ያድርጉ። የJSON ስህተቶችን እንደ {"error": {"code", "message"}} በትክክለኛ የሁኔታ ኮዶች (400፣ 401፣ 403፣ 404፣ 409) ይመልሱ። ሚስጥሮችን በአካባቢ ተለዋዋጮች ያስቀምጡ።
ደህንነት፦
በእያንዳንዱ የቦታ ማስያዣ መንገድ ላይ መግባት ይጠይቁ። በእያንዳንዱ ንባብ፣ ዝማኔ እና ስረዛ ላይ ቦታ ማስያዣው የአሁኑ ተጠቃሚ መሆኑን በሰርቨሩ ላይ ያረጋግጡ፤ ካልሆነ 404 ይመልሱ። የተጠቃሚ IDs ወይም ሚናዎችን ከጥያቄው አካል ፈጽሞ አትቀበሉ። POST /api/bookings በተጠቃሚ በደቂቃ 20 እንዲሆን ይገድቡ። ስህተቶችን በሰርቨሩ ላይ ይመዝግቡ፤ ስታክ ትሬስ ለደንበኛው አትመልሱ።
ሰነዶች፦
የእነዚህን መንገዶች OpenAPI መግለጫ እና ለእያንዳንዱ ምሳሌ ጥያቄዎች እና ምላሾች ያሉት አጭር README ይጻፉ።
ኤፒአይዎን መፈተሽ
ከፍሮንትኤንዱ ውጭ ይሞክሩ፣ አጥቂዎች እንደሚያደርጉት፦
- እያንዳንዱ መንገድ በትክክለኛ ግብዓት ይሰራል እና የተገለጸውን ቅርጽ እና ኮድ ይመልሳል
- የጎደሉ ወይም ልክ ያልሆኑ መስኮች ግልጽ መልዕክት ያለው 400 ይመልሳሉ
- ቶከን ከሌለ በእያንዳንዱ የተጠበቀ መንገድ 401 ይመለሳል
- ተጠቃሚ A የተጠቃሚ B መዝገብ በIDው ሲጠይቅ 404 ወይም 403 ያገኛል
- ዝርዝሮች በገጽ ተከፍለዋል፤ ትልቅ
limitይገደባል - የተባዙ ወይም የሚጋጩ ፍጠሮች 500 ሳይሆን 409 ይመልሳሉ
- የጥያቄ ገደቦች 429 ይመልሳሉ
- የስህተት ምላሾች ስታክ ትሬስ፣ SQL ወይም ሚስጥር አይይዙም
- CORS የሚፈቅደው ያሰቡትን ምንጮች ብቻ ነው
የተለመዱ ስህተቶች
- መግባትን ብቻ ማረጋገጥ፣ ባለቤትነትን አለማረጋገጥ። በጣም የተለመደው የኤፒአይ ክፍተት፦ ማንኛውም የገባ ተጠቃሚ IDውን በመቀየር የማንኛውንም መዝገብ ማንበብ ይችላል።
- ደንበኛውን ማመን። በጥያቄ አካል ውስጥ ያሉ ዋጋዎች፣ ሚናዎች እና የተጠቃሚ IDs ሊቀየሩ ይችላሉ።
- ሙሉ የዳታቤዝ ረድፎችን መመለስ። የይለፍ ቃል ሃሾች እና ውስጣዊ መስኮች ይወጣሉ። እያንዳንዱ ምላሽ ምን እንደሚያካትት ይምረጡ።
- ወሰን የሌላቸው ዝርዝሮች። ለእያንዳንዱ መዝገብ አንድ ጥያቄ ሙሉ መተግበሪያውን ሊያዘገይ ይችላል።
- በውስጡ የስህተት መልዕክት ያለው
200 OK። ደንበኞችና ክትትል መሳሪያዎች ያልተሳካ መሆኑን ማወቅ አይችሉም። - ሁሉን እንዲፈቅድ የተዋቀረ CORS ኩኪዎችን በሚጠቀም ኤፒአይ ላይ።
- የጤና ፍተሻ ወይም ምዝግብ የለም፤ ስለዚህ ስለመቋረጥ የምታውቁት ከተጠቃሚዎች ነው።
ለሰፊ ቅድመ-ማስጀመሪያ ማረጋገጫ፣ ለAI-የተገነቡ መተግበሪያዎች የደህንነት ማረጋገጫ ዝርዝር ይመልከቱ።
በMythex REST API መገንባት
ኤፒአይን እንደ የመተግበሪያዎ አካል ወይም እንደ የራሱ አገልግሎት ከMythex መጠየቅ ይችላሉ። የሰነዱ የምግብ አሰራር REST API backend የመነሻ ጥያቄ አለው፦ ፍሬምወርካችሁን እና መንገዶቹን ይጥቀሱ፣ ግልጽ የJSON ስህተቶች እንዲሰጡ ይጠይቁ፣ ሚስጥሮችን በአካባቢ ተለዋዋጮች ያስቀምጡ፣ እና Dockerfile ያካትቱ። በNode፣ Python፣ C#፣ Java እና ሌሎች ያሉ ኮንቴይነር ባክኤንዶች በDockerfile በኩል ይታተማሉ፤ Mythex ማሰማራቱን ከPublish ያስተናግዳል (API backends)። ፕሮጀክት ድረ-ገጽ እና የኤፒአይ ሰርቨር ጎን ለጎን ማስኬድ ይችላል፤ በቅድመ-እይታ ውስጥ መካከል መቀያየር ይችላሉ። ሚስጥሮችን እንደ የፕሮጀክት ሚስጥሮች ያስቀምጡ፤ ኤፒአዩ ዳታቤዝ የሚያስፈልገው ከሆነ በውይይት ይጠይቁ። ከኤፒአይዎ ጋር ለሚገናኙ መርሐግብር የተያዙ ስራዎች የጀርባ ስራዎችን እንዴት ማስኬድ ይመልከቱ።
ጥያቄዎች
REST API ምንድን ነው?
REST API ፕሮግራሞች በHTTP ላይ ከመተግበሪያዎ ዳታ ጋር እንዲሰሩ የሚያስችል መንገድ ነው። እያንዳንዱ የዳታ አይነት እንደ /orders ያለ የራሱ URL ያለው ግብዓት ነው፤ መደበኛ ዘዴዎችም በእሱ ላይ ይሰራሉ፦ GET ለማንበብ፣ POST ለመፍጠር፣ PATCH ወይም PUT ለማዘመን፣ እና DELETE ለማስወገድ። ዳታ በአብዛኛው በJSON ይላካል።
REST API በየትኛው ቋንቋ ልገነባ?
እርስዎ ወይም ቡድንዎ ማቆየት የሚችሉትን ይጠቀሙ። Node.js ከExpress ወይም Fastify ጋር፣ Python ከFastAPI ጋር፣ እና C# ወይም Java ፍሬምወርኮች ሁሉም በደንብ ይሰራሉ። ለመንገዶች፣ ለሁኔታ ኮዶች፣ ለማረጋገጫ እና ለማረጋገጫ ያሉት የዲዛይን ህጎች ከቋንቋው በላይ ይበልጥ ያስፈልጋሉ።
REST API እንዴት ልጠብቀው?
ለእያንዳንዱ ህዝብ ያልሆነ መንገድ ማረጋገጫ ይጠይቁ፤ ጥሪ አቅራቢው እያንዳንዱን የተለየ መዝገብ ማግኘት እንደሚችል በሰርቨሩ ላይ ያረጋግጡ፤ ሁሉንም ግብዓት ያረጋግጡ፤ HTTPS ይጠቀሙ፤ የጥያቄዎችን ብዛት ይገድቡ፤ ሚስጥሮችን በአካባቢ ተለዋዋጮች (environment variables) ያስቀምጡ። ከደንበኛው የተላኩ IDs ወይም ሚናዎችን ፈጽሞ አትመኑ።
ለREST API የተለየ ባክኤንድ ያስፈልገኛል?
ሁልጊዜ አያስፈልግም። እንደ Next.js ያሉ ፍሬምወርኮች የኤፒአይ መንገዶችን ከገጾች ጎን ማቅረብ ይችላሉ። የተለየ የኤፒአይ አገልግሎት የሚያስፈልገው ብዙ ደንበኞች (ድር፣ ሞባይል፣ አጋሮች) ሲጠቀሙት ወይም የራሱ ቋንቋ ወይም ስኬሊንግ ሲፈልግ ነው።