როგორ შევქმნათ REST API: დიზაინი, უსაფრთხოება და დეპლოიმენტი
REST API-ის შესაქმნელად ჩამოთვალეთ რესურსები, რომლებსაც თქვენი აპი მართავს (მომხმარებლები, შეკვეთები, დაჯავშნები), მიანიჭეთ თითოეულს URL, მაგალითად /orders და /orders/{id}, და მოქმედებებისთვის გამოიყენეთ HTTP მეთოდები: GET კითხვისთვის, POST შექმნისთვის, PATCH განახლებისთვის, DELETE წაშლისთვის. დააბრუნეთ JSON აზრიანი სტატუს კოდებით, გაუკეთეთ ვალიდაცია ყველა შემავალ მონაცემს, მოითხოვეთ ავტორიზაცია და სერვერზე ჩანაწერ-დონის უფლებების შემოწმება, და სიები დაყავით გვერდებად. შემდეგ დაადოკუმენტირეთ ენდპოინტები და დაადეპლოიეთ API HTTPS-ის უკან.
ეს გზამკვლევი მოიცავს დიზაინის გადაწყვეტილებებს, მარშრუტების სამუშაო ნაკრებს, მოთხოვნებს AI აპის შემქმნელისთვის და იმ შეცდომებს, რომლებიც უსაფრთხოების ხვრელებს ქმნის. თუ API თქვენთვის ახალია, დაიწყეთ რა არის API.
როდის გჭირდებათ REST API
- თქვენს ვებ ფრონტენდს სჭირდება მონაცემების შენახვა და ჩატვირთვა სერვერიდან
- მობილურ აპს, პარტნიორს ან ავტომატიზაციის ინსტრუმენტს სჭირდება წვდომა თქვენს მონაცემებზე
- სხვა სერვისები გიგზავნიან მოვლენებს (webhooks)
- თქვენ ფრონტენდსა და ბექენდის გუნდს შორის ანაწილებთ სამუშაოს
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. ღირს შემდეგი კონვენციების დაცვა:
- მრავლობითი არსებითი სახელები, ზმნების გარეშე 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. მონაცემები შეინახე ჩვენს მონაცემთა ბაზაში. მოთხოვნის სხეული დაამოწმე სქემის ბიბლიოთეკით და უარყავი უცნობი ველები. JSON შეცდომები დააბრუნე ფორმატით {"error": {"code", "message"}} სწორი სტატუს კოდებით (400, 401, 403, 404, 409). საიდუმლოებები შეინახე გარემოს ცვლადებში.
უსაფრთხოება:
მოითხოვე შესვლა ყველა bookings მარშრუტზე. ყველა კითხვაზე, განახლებასა და წაშლაზე სერვერზე შეამოწმე, რომ დაჯავშნა მიმდინარე მომხმარებელს ეკუთვნის; თუ არა, დააბრუნე 404. მოთხოვნის სხეულიდან არასდროს მიიღო მომხმარებლის ID-ები ან როლები. შეზღუდე POST /api/bookings 20-მდე წუთში, მომხმარებელზე. ლოგე შეცდომები სერვერზე სტეკის კვალის დაბრუნების გარეშე.
დოკუმენტაცია:
დაწერე ამ მარშრუტების OpenAPI აღწერა და მოკლე README, მაგალითი მოთხოვნებითა და პასუხებით თითოეულისთვის.
თქვენი API-ის ტესტირება
ტესტირება გარე ფრონტენდიდან მოახდინეთ, რადგან თავდამსხმელებიც ასე იქცევიან:
- თითოეული მარშრუტი მუშაობს სწორ მონაცემზე და აბრუნებს დოკუმენტირებულ ფორმას და კოდს
- ნაკლული ან არასწორი ველები აბრუნებს 400-ს ნათელი შეტყობინებით
- ტოკენის გარეშე ყველა დაცულ მარშრუტზე აბრუნებს 401-ს
- მომხმარებელი A-ს მიერ მომხმარებელი B-ს ჩანაწერის ID-ით მოთხოვნა აბრუნებს 404-ს ან 403-ს
- სიები გვერდებადაა დაყოფილი; უზარმაზარი
limitშეზღუდულია - დუბლიკატი ან კონფლიქტური შექმნები აბრუნებენ 409-ს, არა 500-ს
- ლიმიტები აბრუნებენ 429-ს
- შეცდომის პასუხები არ შეიცავს სტეკის კვალს, SQL-ს ან საიდუმლოებებს
- CORS მხოლოდ თქვენს სასურველ წყაროებს უშვებს
გავრცელებული შეცდომები
- შესვლის შემოწმება, მაგრამ არა კუთვნილების. ყველაზე გავრცელებული API ხვრელი: ნებისმიერ შესულ მომხმარებელს შეუძლია ნებისმიერი ჩანაწერის წაკითხვა ID-ის შეცვლით.
- კლიენტისთვის ნდობა. ფასები, როლები და მომხმარებლის ID-ები მოთხოვნის სხეულიდან შეიძლება შეიცვალოს.
- მთლიანი მონაცემთა ბაზის მწკრივების დაბრუნება. პაროლის ჰეშები და შიდა ველები გამოჟონავს. აირჩიეთ, რას შეიცავს თითოეული პასუხი.
- შეუზღუდავი სიები. ერთი მოთხოვნა ყველა ჩანაწერზე შეუძლია მთელი აპი შეანელოს.
200 OKშეცდომის შეტყობინებით შიგნით. კლიენტები და მონიტორინგი ვერ ხვდებიან, რომ წარუმატებლობა მოხდა.- CORS ყველას დაშვებაზე, API-ზე, რომელიც cookie-ებს იყენებს.
- ჯანმრთელობის შემოწმებისა და ლოგების გარეშე, ასე რომ, გათიშვებს მომხმარებლებისგან შეიტყობთ.
გაშვებამდე ფართო გადამოწმებისთვის იხილეთ უსაფრთხოების ჩამონათვალი AI-ით აგებული აპებისთვის.
REST API-ის შექმნა Mythex-ში
Mythex-ს შეგიძლიათ სთხოვოთ API, როგორც თქვენი აპის ნაწილი, ან როგორც ცალკე სერვისი. დოკუმენტაციის რეცეპტი REST API backend შეიცავს საწყის მოთხოვნას: დაასახელეთ ფრეიმვორკი და მარშრუტები, მოითხოვეთ ნათელი JSON შეცდომები, საიდუმლოებები გარემოს ცვლადებში შეინახეთ და ჩართეთ Dockerfile. Node, Python, C#, Java და სხვა ენებზე დაფუძნებული კონტეინერული ბექენდები Dockerfile-ით გამოქვეყნდება, ხოლო დეპლოის Mythex Publish-იდან მართავს (API backends). პროექტს შეუძლია ვებსაიტისა და API სერვერის ერთად გაშვება, და მათ შორის გადართვა წინასწარ ნახვაში. საიდუმლოებები შეინახეთ პროექტის საიდუმლოებებად, და თუ API-ს მონაცემთა ბაზა სჭირდება, ჩატში მოითხოვეთ. დაგეგმილი სამუშაოებისთვის თქვენს API-ს გარშემო იხილეთ როგორ გავუშვათ ფონური სამუშაოები.
კითხვები
რა არის REST API?
REST API არის გზა, რომლითაც პროგრამები მუშაობენ თქვენი აპის მონაცემებთან HTTP-ის საშუალებით. მონაცემების თითოეული სახეობა არის რესურსი საკუთარი URL-ით, მაგალითად /orders, და სტანდარტული მეთოდები მასზე მოქმედებენ: GET კითხვისთვის, POST შექმნისთვის, PATCH ან PUT განახლებისთვის და DELETE წაშლისთვის. მონაცემები, როგორც წესი, JSON ფორმატში იგზავნება.
რა ენაზე უნდა შევქმნა REST API?
გამოიყენეთ ის, რისი შენარჩუნებაც თქვენ ან თქვენს გუნდს შეუძლია. Node.js Express ან Fastify-ით, Python FastAPI-ით და C# ან Java ფრეიმვორკები ყველა კარგად მუშაობს. მარშრუტების, სტატუს კოდების, ვალიდაციისა და ავტორიზაციის წესები ენაზე უფრო მნიშვნელოვანია.
როგორ დავიცვა REST API?
მოითხოვეთ ავტორიზაცია ყველა არაპუბლიკურ მარშრუტზე, სერვერზე შეამოწმეთ, აქვს თუ არა გამომძახებელს უფლება კონკრეტულ ჩანაწერზე წვდომისა, ვალიდაცია გაუკეთეთ მთელ შემავალ მონაცემს, გამოიყენეთ HTTPS, შეზღუდეთ მოთხოვნების სიხშირე და საიდუმლოებები ინახეთ გარემოს ცვლადებში. კლიენტის მიერ გაგზავნილ ID-ებსა და როლებს არასდროს ენდოთ.
მჭირდება ცალკე backend REST API-სთვის?
ყოველთვის არა. ისეთი ფრეიმვორკები, როგორიც Next.js-ია, გვერდებთან ერთად API მარშრუტებსაც ემსახურებიან. ცალკე API სერვისი მაშინ აზრიანია, როცა მას რამდენიმე კლიენტი (ვებ, მობილური, პარტნიორები) იყენებს ან როცა მას საკუთარი ენა ან მასშტაბირება სჭირდება.