ბიბლიოთეკა
00/07 · ~36 წთ
GUIDEDECK · ინტერფეისები, რომლებზეც სხვები აშენებენ

API
დიზაინი & კონტრაქტები,
რომლებიც თქვენს კოდზე დიდხანს იცოცხლებს.

36-წუთიანი სამუშაო სესია იმაზე, როგორ ავაგოთ HTTP API-ები, რომელთა გამოყენებაც ადამიანებს ნამდვილად სიამოვნებთ — რესურსების მოდელირება, არჩევანი REST/GraphQL/gRPC-ს შორის, პაგინაცია და შეცდომები, ვერსიონირება, იდემპოტენტურობა და ავთენტიფიკაცია, და კონტრაქტის ჯერ დაწერა. გულახდილები ვიქნებით იმაზეც, სად იმარჯვებს მოსაწყენი ვარიანტი.

~36 წთდამწყები → საშუალოHTTP / ვებ API
გადაახვიეთ
01 · რა ხდის API-ს კარგს 4 წთ

API არის დაპირება,
რომელიც წლების განმავლობაში უნდა შეასრულოთ.

იმ წამიდან, როცა ვინმე თქვენი ენდპოინტისთვის კოდს წერს, თქვენ უკვე ხელმოწერილი გაქვთ კონტრაქტი. შიგნით ყველაფრის გადაწერა თავისუფლად შეგიძლიათ, მაგრამ ის, რაც ქსელში გადის — URL-ები, ველები, სტატუს-კოდები — ახლა უკვე ყველა დანარჩენის დასაყრდენია. კარგი API დიზაინი არის დისციპლინა, რომელიც ამ დაპირებას ადვილად წასაკითხს, ძნელად არასწორად გამოსაყენებელს და უსაფრთხოდ გასაზრდელს ხდის.

API — Application Programming Interface — არის კონტრაქტი, რომელსაც პროგრამის ერთი ნაწილი აქვეყნებს, რომ სხვებმა გამოიყენონ ისე, რომ არ იცოდნენ, როგორ მუშაობს ის შიგნით. ამ დეკში ვგულისხმობთ ვებ API-ებს: სერვერი აქვეყნებს ენდპოინტებს HTTP-ზე, კლიენტები კი — ბრაუზერები, მობილური აპლიკაციები, სხვა სერვისები — მათ იძახებენ. ქვემოთ არსებული ტრანსპორტი (TCP, TLS, HTTP) აღწერილია ქსელებში.

სამი თვისება, რომელსაც მნიშვნელობა აქვს

  • თანმიმდევრულობა — ერთი და იგივე იდეა ყველგან ერთნაირად გამოიყურება. როგორც კი გამომძახებელი ერთ ენდპოინტს ისწავლის, შემდეგი ნაცნობად უნდა მოეჩვენოს დოკუმენტაციის კითხვის გარეშე.
  • პროგნოზირებადობა — სახელები, შეცდომები და სტატუს-კოდები ზუსტად იმას ნიშნავს, რასაც გონივრული ადამიანი ელოდება. არანაირი სიურპრიზი და არანაირი "200 OK", რომელშიც შეცდომაა შეფუთული.
  • განვითარებადობა — შეგიძლიათ ახალი შესაძლებლობა დაამატოთ ისე, რომ არ გატეხოთ ის, ვინც უკვე ინტეგრირდა. კონტრაქტი იზრდება; ის არ იმსხვრევა.

კლიენტი დამოკიდებულია კონტრაქტზე, და არა თქვენს კოდზე. შეინარჩუნეთ კონტრაქტი სტაბილურად და მის უკან ყველაფრის რეფაქტორინგი შეგეძლებათ.

∞

კლიენტი, რომელსაც არასდროს შეხვდებით, შეიძლება იმ ველზე იყოს დამოკიდებული, რომელსაც პრივატულად თვლიდით.

ნაკლები სიურპრიზი

საუკეთესო API ის არის, რომელსაც დეველოპერი პირველივე ცდაზე სწორად გამოიცნობს.

შეცდომა რთულია

გახადეთ სწორი გამოძახება აშკარა, სახიფათო კი — მოუხერხებელი ან შეუძლებელი.

დოკუმენტაცია ხარჯი

ყოველი შეუსაბამობა არის წინადადება, რომელიც ვიღაცამ უნდა დაწეროს — და კიდევ ერთმა ადამიანმა უნდა წაიკითხოს.

02 · რესურსების მოდელი და REST-ის წესები 6 წთ

დაამოდელეთ არსებითი სახელები URL-ებად,
ზმნები კი HTTP მეთოდები იყოს.

REST-ის მთავარი ხრიკი პატარაა, მაგრამ ძლიერი: თქვენი URL-ები ასახელებს საგნებს (რესურსებს), HTTP მეთოდი კი ამბობს, რას აკეთებთ ამ საგანთან. GET /orders/42 კითხულობს შეკვეთა 42-ს; DELETE /orders/42 შლის მას. აღარ იგონებთ ახალ ენდპოინტს ყოველი ქმედებისთვის და ეყრდნობით რამდენიმე მეთოდს, რომელიც ყველამ უკვე იცის.

REST — Representational State Transfer — არის HTTP API-ების სტილი, სადაც სუფთა URL-ებზე აქვეყნებთ რესურსებს (მომხმარებელი, შეკვეთა, კომენტარი) და მათზე მოქმედებთ სტანდარტული HTTP ზმნებით. ეს წესების ნაკრებია და არა მკაცრი სპეციფიკაცია — სწორედ ამიტომ "RESTful" დისციპლინის ძალიან ფართო დიაპაზონს ფარავს. თავად ზმნები და სტატუს-კოდები დეტალურად აღწერილია HTTP მოთხოვნის მეთოდებში.

მრავლობითი სახელები, კუთვნილების მიხედვით ჩადგმული. იგივე ხუთი ზმნა მუშაობს ყველა დონეზე — ყოველი რესურსისთვის ახალი ლექსიკა აღარ გჭირდებათ.

წესები, რომელთა დაცვაც ღირს

  • მრავლობითი სახელები კოლექციებისთვის: /orders და არა /getOrder. ზმნა უკვე მეთოდშია.
  • ჩადგით კუთვნილებით, ზედაპირულად: /orders/42/items კარგია; ხუთი დონე უკვე ცუდი ნიშანია.
  • დეფისი და პატარა ასოები: /shipping-addresses, არასდროს /ShippingAddresses.
  • დააბრუნეთ სწორი სტატუსი — 201 შექმნაზე, 204 სხეულის გარეშე წაშლაზე, 404 მაშინ, როცა ის მართლა აღარ არსებობს.
RPC-სტილი — ზმნა ყოველ ქმედებაზე
// every action invents a new endpoint + verb POST /createOrder POST /getOrderById POST /updateOrderStatus POST /deleteOrder?id=42 POST /addItemToOrder // 200 OK { "error": "not found" } ← lies to the client
რესურსული — სახელები + მეთოდები
// one noun, the method carries the intent POST /orders // 201 Created + Location GET /orders/42 // 200, or 404 if absent PATCH /orders/42 // 200, partial update DELETE /orders/42 // 204 No Content POST /orders/42/items // add a child
PUT vs PATCH

PUT ცვლის მთელ რესურსს; PATCH — მის ნაწილს. აგზავნით მხოლოდ იმ ველებს, რომლებიც შეიცვალა? ეს PATCH-ია.

არა-CRUD ქმედებები

"გამოქვეყნება" ან "თანხის დაბრუნება" ზმნაზე არ აისახება. დაამოდელეთ ისინი ქვე-რესურსად — POST /orders/42/refunds — და არა /refundOrder.

სტატუსი, გულახდილად

2xx წარმატება, 4xx გამომძახებლის ბრალი, 5xx თქვენი. არასდროს დამალოთ შეცდომა 200-ის შიგნით.

03 · REST თუ GraphQL თუ gRPC 6 წთ

სამი პროტოკოლი, სამი
გულახდილი კომპრომისი.

REST, GraphQL და gRPC რეიტინგი არ არის — ისინი პასუხებია სხვადასხვა შეკითხვაზე იმის შესახებ, ვინ და როგორ გიძახებთ. გუნდების უმეტესობამ REST-ით უნდა დაიწყოს და დანარჩენებს მაშინ მიმართოს, როცა კონკრეტული ტკივილი გამოჩნდება: REST-ის ზედმეტი მონაცემების წამოღება ან შიდა ქსელის შეყოვნების ბიუჯეტი.

განსხვავება ერთ წინადადებაში — REST გაძლევთ ბევრ რესურსის URL-ს და კლიენტი იმას იღებს, რასაც აძლევენ; GraphQL გაძლევთ ერთ ენდპოინტს და კლიენტი ზუსტად იმ ველებს ირჩევს, რომლებიც უნდა; gRPC გაძლევთ ტიპიზებულ ფუნქციურ გამოძახებებს სწრაფ ბინარულ პროტოკოლზე. ისინი თანაარსებობენ: REST საჯარო კიდეზე, gRPC შიდა სერვისებს შორის, GraphQL კი BFF-ში მდიდარი ფრონტენდებისთვის.
GET /user → დიდი
კლიენტი
GET /orders
GET /prefs
{ user { name, orders { total } } }
→ ზუსტად ეს ველები
კლიენტი
REST · ზედმეტი + ბევრი გასვლა
GraphQL · ველები, ერთი გასვლა

REST-ს შეუძლია ზედმეტი მონაცემი წამოიღოს და ერთი ეკრანისთვის რამდენიმე გამოძახება მოითხოვოს; GraphQL ამას ერთ, ზუსტად ჩამოყალიბებულ მოთხოვნად კეცავს.

რისთვის არის სინამდვილეში თითოეული

  • REST — უნივერსალური ნაგულისხმევი. ქეშირებისთვის მოსახერხებელი, curl-ით დებაგირებადი, ყველასთვის გასაგები. სწორი პასუხი საჯარო API-ების უმეტესობისთვის.
  • GraphQL — როცა ბევრ სხვადასხვა კლიენტს ერთი და იმავე გრაფის სხვადასხვა ნაჭერი სჭირდება და ზედმეტი წამოღება რეალური ტკივილია. სამაგიეროდ სერვერზე სირთულეს იღებთ.
  • gRPC — შიდა, მაღალი გამტარუნარიანობის და დაბალი შეყოვნების სერვისული გამოძახებები, სადაც მკაცრი სქემა და კოდის გენერაცია ამართლებს. ბრაუზერისთვის ბუნებრივი არაა.

ინსტრუმენტების ლანდშაფტი — სამი სტილი, გულახდილად

GET /v1/orders/42 HTTP/1.1 Accept: application/json // → 200 OK { "id": "42", "total": 90, "status": "paid" }

დადებითი — უნივერსალური, HTTP შრეზე ქეშირებადი, ადვილად დებაგირებადი, უზარმაზარი ეკოსისტემა.

უარყოფითი — ზედმეტი ან ნაკლები წამოღება; ერთი ეკრანი შეიძლება რამდენიმე გასვლას ნიშნავდეს; ჩაშენებული სქემა არ აქვს.

აირჩიეთ საჯარო API-ებისთვის, ფართო მოცვისთვის და ყველაფრისთვის, რისი ქეშირებაც ან curl-ით გამოძახებაც გინდათ.

# ერთი ენდპოინტი, კლიენტი აყალიბებს შედეგს query { order(id: "42") { total items { name } # მხოლოდ ის, რაც UI-ს სჭირდება } }

დადებითი — კლიენტი ზუსტ ველებს ირჩევს; ერთი გასვლა მრავალფეროვანი ინტერფეისისთვის; ძლიერი ტიპიზებული სქემა.

უარყოფითი — ქეშირება, სიხშირის ლიმიტი და N+1 შეკითხვები თქვენი პრობლემა ხდება; სერვერის სირთულე იზრდება.

აირჩიეთ მდიდარი, კლიენტზე ორიენტირებული ფრონტენდებისა და ბევრი წყაროს შემკრები BFF-ებისთვის.

// ჯერ სქემა; codegen აგებს კლიენტსა და სერვერს service Orders { rpc Get(OrderId) returns (Order); } message Order { string id = 1; int32 total = 2; }

დადებითი — სწრაფი HTTP/2 ბინარული, მკაცრი protobuf სქემა, სტრიმინგი, გენერირებული კლიენტები ბევრ ენაზე.

უარყოფითი — ბრაუზერისთვის ბუნებრივი არაა (სჭირდება gRPC-Web); თვალით ძნელი წასაკითხია; ინსტრუმენტები უფრო მძიმეა.

აირჩიეთ შიდა, სერვისიდან სერვისზე ტრაფიკისთვის მკაცრი შეყოვნების ბიუჯეტით.

თითქოს  მენიუ, თვითშედგენილი კერძი და მუდმივი შეკვეთა: REST მზა კერძებს გაწვდით, GraphQL თითოეულ სტუმარს თავისი თეფშის შედგენის საშუალებას აძლევს, gRPC კი წინასწარ შეთანხმებული კონტრაქტია სამზარეულოსა და მის მომწოდებლებს შორის. თუ ეჭვობთ, დაიწყეთ REST-ით — დანარჩენების დამატება იქ შეგიძლიათ, სადაც ისინი თავს ამართლებენ.

04 · პაგინაცია, ფილტრაცია და შეცდომების ფორმა 5 წთ

არასდროს დააბრუნოთ
უსაზღვრო სია.

პირველივე ჯერზე, როცა კოლექციაში ათი ათასი სტრიქონი აღმოჩნდება, ენდპოინტი, რომელიც "ყველას" აბრუნებს, ვარდება. პაგინაცია, ფილტრაცია და შეცდომის თანმიმდევრული ფორმა ის მოსაწყენი დეტალებია, რომლებზეც არის დამოკიდებული, გაუძლებს თუ არა თქვენი API რეალურ მონაცემებს — ამიტომ ისინი წინასწარ დააპროექტეთ და არა ინციდენტის შემდეგ.

პაგინაცია — დიდი კოლექციის დაბრუნება შეზღუდული ზომის გვერდებად, ერთბაშად ყველაფრის ნაცვლად. ორი გავრცელებული სტილი: offset (გამოტოვე N, აიღე M — მარტივია, მაგრამ ცურავს და სიის სიღრმეში ნელდება) და კურსორი (გაუმჭვირვალე ტოკენი, რომელიც სტაბილურ პოზიციაზე მიუთითებს — მასშტაბირდება და ჩამატებებსაც უძლებს). დიდი ან სწრაფად ცვალებადი მონაცემებისთვის კურსორი იმარჯვებს.
OFFSET · ?offset=20&limit=10 skip 20 an insert shifts rows → dup/skip slow at deep offsets CURSOR · ?after=ord_88 anchor: ord_88 stable under inserts · indexed seek next = id of last row returned

offset-ს შეუძლია სტრიქონები გამოტოვოს ან გააორმაგოს, თუ სია სქროლის შუაში შეიცვალა; კურსორი კი რეალურ სტრიქონს ეჭიდება და პირდაპირ მასთან გადადის.

ფილტრაცია & დახარისხება, რომელიც გონივრული რჩება

  • ფილტრები query პარამეტრებად: ?status=paid&created_after=2026-01-01. სახელები თქვენს ველების სახელებს შეუსაბამეთ.
  • ერთი დახარისხების პარამეტრი: ?sort=-created_at (წინ დასმული - ნიშნავს კლებადობას) ხუთ სპეციალურ ფლაგზე უკეთესია.
  • დააბრუნეთ გვერდების მეტამონაცემები — შემდეგი კურსორი და არსებობს თუ არა გაგრძელება — რომ კლიენტს გამოცნობა არასდროს დასჭირდეს.
  • ყოველთვის შემოსაზღვრეთ limit სერვერის მხარეს. კლიენტმა, რომელიც 1,000,000-ს ითხოვს, ჩუმად თქვენი მაქსიმუმი უნდა მიიღოს.
// კურსორული პასუხი — მონაცემები + როგორ გავაგრძელოთ { "data": [ { "id": "ord_88" }, /* … */ ], "page": { "next": "ord_98", // გადაეცი როგორც ?after= "has_more": true } }
// RFC 9457 problem details — ერთი ფორმა ყველა შეცდომისთვის // Content-Type: application/problem+json (HTTP 422) { "type": "https://api.acme.com/errors/validation", "title": "Invalid request", "status": 422, "detail": "total must be a positive integer", "errors": [ { "field": "total", "code": "min" } ] }

ერთი პროგნოზირებადი შეცდომის კონვერტი მთელ API-ზე სჯობს ყოველ ენდპოინტზე სხვადასხვა ფორმას. RFC 9457 სწორედ ეს სტანდარტული ფორმაა.

მანქანურად წასაკითხი კოდი

ჩადეთ სტაბილური code სტრიქონი, რომელზეც კლიენტები დატოტვას შეძლებენ. ადამიანისთვის განკუთვნილი detail ტექსტი შეიცვლება; კოდი — არა.

სწორი სტატუსი + სხეული

400 გაფუჭებული ფორმა, 401/403 წვდომა, 404 არ არსებობს, 409 კონფლიქტი, 422 ვალიდაცია. სტატუსი და სხეული ერთმანეთს უნდა ეთანხმებოდეს.

არ გაამჟღავნოთ შიგნეული

შეცდომის სხეულში არც სტეკის ტრეისი და არც SQL. დეტალები სერვერზე დაალოგეთ; გამომძახებელს კი მოწესრიგებული, უსაფრთხო ფორმა დაუბრუნეთ.

05 · ვერსიონირება და უკუთავსებადობა 5 წთ

დაამატეთ თავისუფლად. წაშალეთ და
გადაარქვით მხოლოდ ახალ ვერსიაში.

ყოველი ინტეგრირებული კლიენტი გაყინულია იმ კონტრაქტზე, რომლისთვისაც კოდი დაწერა. ვერსიონირების ყველაზე იაფი სტრატეგია ის არის, რომ ახალი ვერსია თითქმის არასდროს დაგჭირდეთ — API შეცვალეთ ისე, რომ არსებული გამომძახებლები ვერ გატყდნენ. როცა მართლა რაღაცის გატეხვა გიწევთ, გააკეთეთ ეს ღიად და გრაფიკით.

უკუთავსებადი — ცვლილება უსაფრთხოა, თუ ძველი კონტრაქტისთვის დაწერილი ყოველი კლიენტი უცვლელად აგრძელებს მუშაობას. დამატებითი ცვლილებები — ახალი არასავალდებულო ველები, ახალი ენდპოინტები, ახალი არასავალდებულო პარამეტრები — უსაფრთხოა. მრღვევი ცვლილებები — ველის წაშლა ან გადარქმევა, ტიპის გამკაცრება, რაღაცის სავალდებულოდ ქცევა — ყველა გამომძახებელს განახლებას აიძულებს, ამიტომ მათ ახალი ვერსია სჭირდებათ.

არასავალდებულო ველის დამატება არავის ვნებს. მისი გადარქმევა ან წაშლა კი ჩუმად ტეხს ყველა კლიენტს, რომელიც ჯერ კიდევ ძველ სახელს კითხულობს.

სად მოვათავსოთ ვერსია

  • URL-ის გზა — /v1/orders. პირდაპირი, მაგრამ აშკარა, ადვილად ქეშირებადი და მარშრუტიზირებადი. ყველაზე გავრცელებული არჩევანი.
  • ჰედერი — Accept: application/vnd.acme.v2+json ან თარიღზე დაფუძნებული ვერსიის ჰედერი. URL-ებს სუფთად ტოვებს; სამაგიეროდ დანახვა და ტესტირება უფრო რთულია.
  • ვერსიის გარეშე, მხოლოდ დამატებით განვითარება — შესაძლებელია, თუ მკაცრად უკუთავსებადი რჩებით. საუკეთესო ვერსია ის არის, რომელიც არასდროს გამოგიშვიათ.
ტეხს, ჩუმად
// same /v1 endpoint, payload changed underneath // before { "name": "Dani Ortiz" } // after — split into two, dropped "name" { "first": "Dani", "last": "Ortiz" } // every client reading .name now gets undefined ✕
დამატება, მერე დეპრეკაცია
// keep the old field, add the new ones { "name": "Dani Ortiz", // kept, marked deprecated "first": "Dani", "last": "Ortiz" } // announce a sunset date → remove in /v2 later
დეპრეკაცია და არა წაშლა

მონიშნეთ ველი მოძველებულად, გააგზავნეთ Deprecation / Sunset ჰედერი და კლიენტებს რეალური დრო მიეცით, სანამ ის გაქრება.

ტოლერანტი მკითხველი

კლიენტებმა უცნობი ველები უნდა უგულებელყონ და არ გაიგუდონ მათზე — სწორედ ეს ხდის დამატებით ცვლილებებს უსაფრთხოს.

ცოტა ვერსია, დიდხანს

/v1 → /v2 ნორმალურია; ახალი ვერსია ყოველ კვარტალში კი მხარდაჭერის კოშმარია. ვერსიები იშვიათი და ხანგრძლივი გახადეთ.

06 · იდემპოტენტურობა, ლიმიტები და წვდომა 6 წთ

გახადეთ ხელახალი მცდელობა უსაფრთხო, ბოროტად გამოყენება
შეზღუდული, წვდომა კი დამტკიცებული.

რეალურ ქსელებში პასუხები იკარგება, კლიენტები იმეორებენ მოთხოვნას და ყველა, ვინც გიძახებთ, კეთილგანწყობილი არაა. საჯარო API-ს სანდოობას სამი მექანიზმი ინარჩუნებს: იდემპოტენტურობა, რომ გამეორებულმა ჩაწერამ ორჯერ არ ჩამოჭრას თანხა, სიხშირის ლიმიტი, რომ ერთმა გამომძახებელმა დანარჩენები არ დააშიმშილოს, და ავთენტიფიკაცია, რომ იცოდეთ, ვინ არის ხაზზე.

იდემპოტენტური — ერთი და იმავე გამოძახებას ორჯერ იგივე ეფექტი აქვს, რაც ერთხელ. GET, PUT და DELETE განსაზღვრებით იდემპოტენტურია; POST — არა. ამიტომ POST-ისთვის, რომელიც თანხას ჭრის, კლიენტი აგზავნის იდემპოტენტურობის გასაღებს, სერვერი კი შედეგს იმახსოვრებს და მეორედ ჭრის ნაცვლად თავდაპირველ პასუხს აბრუნებს.

ხელახალი მცდელობა იმავე Idempotency-Key-ს ატარებს; სერვერი ცნობს მას და შენახულ შედეგს იმეორებს — ერთი ჩამოჭრა და არა ორი.

# კლიენტი აგენერირებს უნიკალურ გასაღებს ყოველ ლოგიკურ მოთხოვნაზე POST /v1/charges Idempotency-Key: 8f3c1a90-... # იგივე ყოველ გამეორებაზე { "amount": 9000, "currency": "usd" } # პირველი გამოძახება → ქმნის და ინახავს შედეგს გასაღების ქვეშ # გამეორება → აბრუნებს იმავე პასუხს, ახალი ჩამოჭრის გარეშე

პატერნი Stripe-მა გაავრცელა; Idempotency-Key ჰედერი დღეს გავრცელებული წესია იმ ჩაწერებისთვის, რომელთა გამეორებაც უსაფრთხოა.

სიხშირის ლიმიტი — დაიცავით საერთო რესურსი

  • შემოსაზღვრეთ მოთხოვნები თითო კლიენტზე თითო ფანჯარაში (ჩვეულებრივი მექანიზმია ტოკენების ვედრო — ივსება მუდმივი სიჩქარით, იხარჯება ყოველ გამოძახებაზე).
  • ლიმიტს ზემოთ → 429 Too Many Requests და Retry-After ჰედერი, რომ კლიენტმა თავაზიანად დაიხიოს.
  • გამოაცხადეთ ბიუჯეტი RateLimit-* პასუხის ჰედერებით (ლიმიტი, ნარჩენი, განულების დრო), რომ კარგმა კლიენტებმა თავად შეიზღუდონ თავი.

Auth — authN თუ authZ

  • ავთენტიფიკაცია = ვინ ხარ; ავტორიზაცია = რის უფლება გაქვს. სხვადასხვა შეკითხვაა, თუმცა ხშირად ერევათ.
  • API გასაღებები სერვერიდან სერვერზე სიმარტივისთვის; OAuth 2.0 / OpenID Connect მაშინ, როცა მომხმარებლები წვდომას მესამე მხარეს გადასცემენ.
  • სააუთენტიფიკაციო მონაცემები ატარეთ Authorization: Bearer …-ში TLS-ზე — არასდროს URL-ში, სადაც ისინი ლოგებსა და ისტორიაში ხვდება.
# the server tells the client its budget HTTP/1.1 429 Too Many Requests Retry-After: 30 RateLimit-Limit: 100 RateLimit-Remaining: 0 RateLimit-Reset: 30 # seconds until refill

ტოკენების ვედრო: მოთხოვნები ტოკენებს ხარჯავს, ვედრო მუდმივად ივსება, ცარიელი ვედრო კი 429-ს აბრუნებს დაცდის მინიშნებით.

07 · ჯერ კონტრაქტი, OpenAPI და შეჯამება 4 წთ

ჯერ დაწერეთ კონტრაქტი.
დანარჩენი დააგენერირეთ.

ყველაზე საიმედო API-ები დაწერილი კონტრაქტის სახით იქმნება მანამ, სანამ ჰენდლერის ერთი ხაზი მაინც არსებობს. მანქანურად წასაკითხი სპეციფიკაცია ხდება ჭეშმარიტების ერთადერთი წყარო — დოკუმენტაცია, კლიენტის SDK-ები, მოკ სერვერები და მოთხოვნის ვალიდაცია მისგან მოედინება, და ყველა ფორმაზე თანხმდება მანამ, სანამ ვინმე მას ააგებს.

ჯერ კონტრაქტი / OpenAPI — API-ს აღწერთ ფორმალურ სპეციფიკაციაში (OpenAPI REST-ისთვის, Protobuf gRPC-სთვის, SDL GraphQL-ისთვის) და ამ ფაილს ჭეშმარიტების წყაროდ თვლით. ერთი OpenAPI დოკუმენტიდან შეგიძლიათ ავტომატურად დააგენერიროთ ინტერაქტიული დოკუმენტაცია, ტიპიზებული კლიენტები ბევრ ენაზე, სერვერის დანამატები, მოკ სერვერები და მოთხოვნის ვალიდაცია გაშვების დროს — ასე რომ სპეციფიკაცია და კოდი ერთმანეთს არასდროს სცილდება.
# the contract — the source of truth, not an afterthought paths: /orders/{id}: get: parameters: [{ name: id, in: path, required: true }] responses: "200": { $ref: "#/components/schemas/Order" } "404": { $ref: "#/components/responses/Problem" }

ერთი სპეციფიკაცია, ბევრი არტეფაქტი. დააგენერირეთ დოკუმენტაცია, SDK-ები, მოკები და ვალიდაცია, ნაცვლად იმისა, რომ თითოეული ხელით მოვლოთ.

სპეციფიკაციისა & ინსტრუმენტების ლანდშაფტი

OpenAPI + Swagger / Redoc

აირჩიეთ ჭეშმარიტების წყაროდ ნებისმიერი REST API-სთვის, რომელსაც სხვებიც გამოიყენებენ.

  • დადებითი — REST-ის სტანდარტი; ერთი სპეციფიკაცია კვებავს დოკუმენტაციას, კოდის გენერაციას, მოკებსა და ვალიდაციას.
  • უარყოფითი — დიდი YAML ფაილები რთულად სამართავი ხდება; სპეციფიკაციისა და კოდის სინქრონში შენარჩუნებას დისციპლინა ან გენერაცია სჭირდება.
Postman / Insomnia

აირჩიეთ API-ს ხელით მოსინჯვის, დებაგირებისა და ინტეგრაციული ტესტირებისთვის.

  • დადებითი — სწრაფი ხელით კვლევა, გასაზიარებელი კოლექციები, ავტომატური ტესტების გაშვება ცოცხალ ენდპოინტებზე.
  • უარყოფითი — კოლექცია კონტრაქტი არ არის; თუ სპეციფიკაციას არ მიაბით, ის რეალურ API-ს ასცდება.
Protobuf + gRPC

აირჩიეთ მაშინ, როცა კონტრაქტი შიდა სერვისებს შორისაა gRPC-ზე და არა საჯარო HTTP-ზე.

  • დადებითი — მკაცრი, სქემაზე დაფუძნებული კონტრაქტი კოდის გენერაციით ბევრ ენაზე და ჩაშენებული თავსებადობის წესებით.
  • უარყოფითი — მხოლოდ gRPC; ბრაუზერისთვის ბუნებრივი არაა; ბინარულ შიგთავსს თვალით ვერ შეამოწმებთ.

ხუთი წესი, რომელიც თან უნდა წაიღოთ

1დააპროექტეთ კონტრაქტი და არა კოდი. URL-ები, ველები და სტატუს-კოდები არის დაპირება — შეინარჩუნეთ ისინი თანმიმდევრული და პროგნოზირებადი.
2დაამოდელეთ სახელები, გამოიყენეთ ზმნები. რესურსები სუფთა URL-ებზე, HTTP მეთოდი ატარებს განზრახვას, სტატუს-კოდები კი ყველგან გულახდილია.
3დაიწყეთ REST-ით. GraphQL-ს ან gRPC-ს მაშინ მიმართეთ, როცა რეალური ტკივილი — ზედმეტი წამოღება, შიდა შეყოვნება — სირთულეს ამართლებს.
4განვითარდით, ნუ გატეხავთ. არასავალდებულო ველები თავისუფლად დაამატეთ; წაშალეთ და გადაარქვით მხოლოდ ახალი ვერსიის უკან, გამორთვის ვადით.
5გახადეთ ისეთი, რომ დაყრდნობა უსაფრთხო იყოს. იდემპოტენტური ჩაწერები, შემოსაზღვრული ლიმიტები, რეალური ავთენტიფიკაცია და შეცდომის ერთი თანმიმდევრული ფორმა.
  • ჯერ რესურსები დახაზეთ. სახელები და მათი კუთვნილების ხე ნებისმიერ ენდპოინტამდე.
  • დაწერეთ OpenAPI სპეციფიკაცია და მომხმარებელთან ერთად გადახედეთ მას მანამ, სანამ ჰენდლერებს დაწერთ.
  • აირჩიეთ სწორი სტატუსი + ერთი შეცდომის ფორმა (RFC 9457) და ყველგან ის გამოიყენეთ.
  • დაყავით გვერდებად ყოველი სია, შემოსაზღვრეთ ყოველი ლიმიტი და წინასწარ გადაწყვიტეთ, კურსორი თუ offset.
  • დაგეგმეთ ცვლილება: შემწყნარებელი მკითხველები, დამატებითი ზრდა და ვერსიონირების წესი, რომელსაც მართლა დაიცავთ.
ცოდნის შემოწმება

დაგამახსოვრდათ?

ხუთი სწრაფი შეკითხვა REST-ის წესებზე, პროტოკოლის არჩევანზე, პაგინაციაზე, ვერსიონირებასა და იდემპოტენტურობაზე — მყისიერი პასუხი, შესვლის გარეშე.

შეაფასეთ ეს დასტა
იყავით პირველი

ნავიგაცია ← → ღილაკებით ან სქროლით · უკან ბიბლიოთეკაში