ბიბლიოთეკა
00/08 · ~38 წთ
GUIDEDECK · API-ები, რომლებიც მოსალოდნელად იქცევა

HTTP მოთხოვნის
მეთოდები, სემანტიკა
& REST-ის კონტრაქტი.

38-წუთიანი სამუშაო სესია ვების ზმნებზე — GET, POST, PUT, PATCH, DELETE — მათ უკან მდგარ უსაფრთხოებისა და იდემპოტენტურობის წესებზე, სტატუს-კოდებზე, რომლებსაც მნიშვნელობა აქვს, იმაზე, როგორ დავამოდელიროთ რესურსი ისე, რომ კლიენტები, ქეშები და პროქსები ერთნაირად ხედავდნენ, რას აკეთებს თქვენი ენდპოინტი, და იმ ინსტრუმენტებსა და API-სტილებზე, რომლებსაც პრაქტიკაში მიმართავთ.

~38 წთბექენდი / ფულ-სტეკიპროტოკოლისგან დამოუკიდებელი
გადაახვიეთ
01 · სემანტიკის მნიშვნელობა 4 წთ

მეთოდი არის დაპირება
იმისა, რასაც მოთხოვნა აკეთებს.

HTTP მხოლოდ ბაიტების გადასატანი მილი არაა — ეს საერთო კონტრაქტია. თქვენს კოდსა და სერვერს შორის დგას დამხმარეების მთელი ბრბო: ბრაუზერი, CDN (ედჟ-სერვერების ქსელი, რომელიც ასლებს მომხმარებლებთან ახლოს ინახავს), პროქსები და დატვირთვის ბალანსერები (რელეები, რომლებიც ტრაფიკს გადასცემენ და ანაწილებენ) და თქვენივე ხელახალი მცდელობის ლოგიკა. თითოეული მათგანი კითხულობს მეთოდს და თავად წყვეტს, რა შეუძლია: შეინახოს პასუხი, წინასწარ წამოიღოს იგი (prefetch) თუ ტაიმაუტის შემდეგ ხელახლა გააგზავნოს. დაარღვევთ მეთოდის დაპირებას და მთელი ეს ბრბო ჩუმად თქვენს წინააღმდეგ იმუშავებს.

HTTP — HyperText Transfer Protocol — მოთხოვნა/პასუხის პროტოკოლია, სადაც ყოველი მოთხოვნა აცხადებს მეთოდს (ზმნას), სამიზნეს (URL-ს), რამდენიმე ჰედერს (მეტამონაცემებს) და არასავალდებულო სხეულს. მეთოდი აცხადებს განზრახვას; ყველაფერი, რაც ქვემოთაა, სწორედ ამ განცხადებულ განზრახვაზე ოპტიმიზდება.

გაცვლის ანატომია

  • მოთხოვნის ხაზი — მეთოდი + გზა + ვერსია (GET /users/42 HTTP/1.1).
  • ჰედერები — გასაღები/მნიშვნელობის მეტამონაცემები: ვინ ითხოვს, რა ფორმატს იღებს, ავთენტიფიკაცია, ქეშირების მინიშნებები.
  • სხეული — დატვირთვა (მას მხოლოდ ზოგიერთი მეთოდი ატარებს).
  • პასუხი იმავეს იმეორებს: სტატუსის ხაზი, ჰედერები და სხეული.
მოთხოვნა
Host: api.shop.com · Content-Type: app/json · Authorization: Bearer … · — ჰედერები —
პასუხი
Location: /orders/8801 · Content-Type: app/json · — ჰედერები —
POST /orders HTTP/1.1
HTTP/1.1 201 Created
{ "id": 8801, "status": "open" }
— სხეული —
{ "item": "A12", "qty": 2 }
— სხეული —

შედის მეთოდი + გზა + ჰედერები + სხეული; ბრუნდება სტატუსი + ჰედერები + სხეული. ზედა ზმნა განაგებს ყველაფერს.

რატომ დგას ყველაფერი ზმნაზე

ზმნა იგნორირებულია — „ყველაფერი GET-ია“
// a link a crawler or prefetch can follow… GET /deleteUser?id=42 GET /transferMoney?to=99&amt=500 // GET is "safe" — so a browser prefetch, // a proxy, or a bot can fire this for you. // You just deleted a user by accident.
ზმნა დაცულია — განზრახვა ემთხვევა მეთოდს
// the method states the effect; nothing // safe-by-default can trigger it. DELETE /users/42 POST /transfers // body: { to, amt } // caches won't store it, prefetch won't // fire it, and it reads correctly in a log.

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

02 · მეთოდები სათითაოდ 7 წთ

ხუთი ზმნა აკეთებს საქმეს;
კიდევ ორი მასზე პასუხობს.

GET, POST, PUT, PATCH და DELETE თითქმის ყველაფერს ფარავს, რასაც ააგებთ; HEAD და OPTIONS არსებობს მეტამონაცემებისა და შეთანხმებისთვის. გადაათვალიერეთ თითოეული — მიაქციეთ ყურადღება, რას უშვრება მდგომარეობას და ატარებს თუ არა სხეულს.

მეთოდი (ანუ ზმნა) ასახელებს ქმედებას, რომელიც URL-ზე მდებარე რესურსზე უნდა შესრულდეს. ერთი და იგივე გზა /users/42 ნიშნავს „წაკითხვას“, „ჩანაცვლებას“ ან „წაშლას“ — მთლიანად იმაზეა დამოკიდებული, ზმნა GET-ია, PUT თუ DELETE. არსებითი სახელი URL-ია; ზმნა კი — მეთოდი.

GET — რესურსის წაკითხვა, ცვლილების გარეშე

GET /users/42 GET /users?role=admin&page=2 // მოთხოვნის სხეული არაა. შემავალი მონაცემები URL-ში / query-ში. // უსაფრთხო + იდემპოტენტური + ქეშირებადი. // → 200 OK რესურსით, ან 404 თუ არ არსებობს.
როდის გამოვიყენოთ
მონაცემების წამოღება — ჩანაწერი, კოლექცია, გაფილტრული სია.
არასოდეს
გამოიყენოთ GET მდგომარეობის შესაცვლელად. ის თავისუფლად ქეშირდება და მეორდება; გვერდითი ეფექტები გაგაკვირვებთ.

POST — შექმნა ან „დაამუშავე ეს“

POST /orders Content-Type: application/json { "item": "A12", "qty": 2 } // სერვერი ანიჭებს id-ს და აბრუნებს: // → 201 Created · Location: /orders/8801 // არაიდემპოტენტურია: ორჯერ = ორი შეკვეთა.
როდის გამოვიყენოთ
კოლექციაში ახალი ელემენტის შექმნა ან ნებისმიერი არაიდემპოტენტური ქმედება (გადახდა, გაგზავნა, წარდგენა).
თავისებურება
ახალ id-ს კოლექცია (/orders) წყვეტს, არა კლიენტი.

PUT — მთელი რესურსის ჩანაცვლება

PUT /users/42 { "name": "Ada", "email": "ada@x.io", "role": "admin" } // სრული წარმოდგენა — გამოტოვებული ველები იშლება. // იდემპოტენტურია: იგივე PUT ორჯერ = იგივე საბოლოო მდგომარეობა. // → 200 OK (განახლდა) ან 201 (შეიქმნა ამ id-ზე).
როდის გამოვიყენოთ
ხელთ გაქვთ სრული ახალი მდგომარეობა და id კლიენტს ეკუთვნის.
ხაფანგი
გაგზავნით ნაწილობრივ სხეულს და დაკლებულ ველებს დააცარიელებთ. სწორედ ამისთვისაა PATCH.

PATCH — ნაწილობრივი განახლების გამოყენება

PATCH /users/42 { "role": "editor" } // იცვლება მხოლოდ დასახელებული ველი; დანარჩენი ხელუხლებელია. // → 200 OK განახლებული რესურსით. // იდემპოტენტურია, თუ მნიშვნელობებს ანიჭებს (role = "editor"). // არაიდემპოტენტურია დელტებისთვის (balance += 10).
როდის გამოვიყენოთ
ერთი-ორი ველის შეცვლა მთელი ობიექტის ხელახლა გაგზავნის გარეშე.
სინამდვილეში ეს არის
PUT-ის სკალპელი — იგივე სამიზნე, უფრო მცირე დაზიანების რადიუსი.

DELETE — რესურსის წაშლა

DELETE /users/42 // სხეული საჭირო არაა; სამიზნე URL-ია. // იდემპოტენტურია: ორჯერ წაშლა ერთნაირად სრულდება. // → 200/204 პირველად… // → 404 მეორედ ნორმალურია — მდგომარეობა იდენტურია.
როდის გამოვიყენოთ
ერთი რესურსის წაშლა მისი URL-ით.
იდემპოტენტურია?
დიახ — მდგომარეობა ერთი თუ ათი DELETE-ის შემდეგ ერთი და იგივეა: წაშლილია.

HEAD & OPTIONS — კითხვა რესურსის შესახებ

HEAD /report.pdf // GET-ივით, მხოლოდ ჰედერები — სხეულის გარეშე // → 200 + Content-Length: 4.2MB (შეამოწმეთ ჩამოტვირთვამდე) OPTIONS /orders // რა შემიძლია აქ? // → Allow: GET, POST, OPTIONS // ასევე ამოძრავებს ბრაუზერის CORS preflight-ს.
HEAD
იაფი შემოწმება არსებობაზე / ზომაზე / ქეშირებაზე, სხეულის გადმოტანის გარეშე.
OPTIONS
კითხულობს: „რა შემიძლია აქ?“ ის ასევე ამოძრავებს ბრაუზერის CORS preflight-ს — სწრაფ ნებართვის შემოწმებას, რომელსაც ბრაუზერი ჯვარედინი მოთხოვნის წინ უშვებს, რათა დაადასტუროს, რომ სერვერი მას ნამდვილად უშვებს.
03 · უსაფრთხო & იდემპოტენტური 6 წთ

ორი თვისება წყვეტს, უსაფრთხოა თუ არა
გამეორება.

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

უსაფრთხო — მოთხოვნა არ ცვლის სერვერის მდგომარეობას (სუფთა წაკითხვა). იდემპოტენტური — ერთი და იმავე მოთხოვნის N-ჯერ გაგზავნა იმავე საბოლოო მდგომარეობას ტოვებს, რასაც ერთხელ გაგზავნა. ყოველი უსაფრთხო მეთოდი იდემპოტენტურია; პირიქით კი — არა (PUT და DELETE ცვლიან მდგომარეობას, მაგრამ სუფთად მეორდება).

აზროვნების მოდელის ცხრილი

GET · HEAD

უსაფრთხო ✓ · იდემპოტენტური ✓

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

PUT · DELETE

უსაფრთხო ✕ · იდემპოტენტური ✓

ისინი ცვლიან მდგომარეობას, მაგრამ საბოლოო მდგომარეობა სტაბილურია: ზუსტად ეს სხეული ორჯერ PUT-ით → იგივე ჩანაწერი; ორჯერ DELETE → მაინც წაშლილია. გამეორება უსაფრთხოა.

POST · PATCH*

უსაფრთხო ✕ · იდემპოტენტური ✕

ორჯერ POST ორ რესურსს ქმნის. დელტა-PATCH (balance += 10) გროვდება. გაიმეორეთ მხოლოდ იდემპოტენტურობის დამცავით. *მნიშვნელობის მიმნიჭებელი PATCH იდემპოტენტურია

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

როგორ გავხადოთ POST-ის გამეორება უსაფრთხო

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

POST /charges Idempotency-Key: 5f2c-…-a91 // კლიენტის გენერირებული, უნიკალური { "amount": 500 } // სერვერი: ნანახია ეს გასაღები? → დააბრუნე შენახული 201. // არა? → დაამუშავე ერთხელ, შედეგი შეინახე გასაღებზე.

ჰგავს  გარდერობის ნომერს — ერთი და იმავე ტალონს ორჯერ რომც გადასცეთ, მაინც ერთ პალტოს დაგიბრუნებენ.

04 · მნიშვნელოვანი სტატუს-კოდები 5 წთ

პასუხის პირველი ხაზი
მისი განაჩენია.

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

სტატუს-კოდი შედეგს პირველი ციფრით ალაგებს: 2xx წარმატება, 3xx გადამისამართება, 4xx გამომძახებელი შეცდა, 5xx სერვერი ჩავარდა. სწორად აირჩიეთ კლასი და კლიენტები, მონიტორინგი და გამეორებები ავტომატურად სწორად მოიქცევა.
2
წარმატება
იმუშავა
3
გადამისამართება
ეძებეთ სხვაგან
4
კლიენტის შეცდომა
თქვენი მოთხოვნა არასწორია
5
სერვერის შეცდომა
ჩვენი ბრალია, სცადეთ ხელახლა
2
2xx — წარმატება
მოთხოვნა მიღებულია, გაგებულია და დამტკიცებულია.
+
  • 200 OK — ნაგულისხმევი წარმატება; შედეგს სხეული ატარებს (GET, PUT, PATCH).
  • 201 Created — POST-მა ახალი რესურსი შექმნა; დააბრუნეთ მისი Location ჰედერი.
  • 202 Accepted — რიგში ჩადგა ასინქრონული სამუშაოსთვის; ჯერ არაა შესრულებული, მაგრამ მიღებულია.
  • 204 No Content — წარმატება, როცა დასაბრუნებელი არაფერია (DELETE-ის ჩვეული პასუხი).
3
3xx — გადამისამართება
რესურსი სხვაგანაა ან არ შეცვლილა.
+
  • 301 Moved Permanently — განაახლეთ ბმულები; ქეშები და SEO სამუდამოდ მიჰყვება.
  • 302 / 307 Found / Temporary — ჯერჯერობით აქ წადით; 307 მეთოდს ინარჩუნებს.
  • 304 Not Modified — თქვენი ქეშირებული ასლი ისევ ახალია; სხეული არ იგზავნება. პირობითი GET-ების ხერხემალი (ნაწილი 6).
4
4xx — კლიენტის შეცდომა
უცვლელად ნუ გაიმეორებთ — ჯერ გაასწორეთ მოთხოვნა.
+
  • 400 Bad Request — დამახინჯებული სინტაქსი ან არავალიდური დატვირთვა.
  • 401 Unauthorized — არ ხართ ავთენტიფიცირებული (სინამდვილეში „არაავთენტიფიცირებული“).
  • 403 Forbidden — ავთენტიფიცირებული ხართ, მაგრამ უფლება არ გაქვთ.
  • 404 Not Found · 409 Conflict (ვერსიების შეჯახება) · 422 Unprocessable (ვალიდური სინტაქსი, დარღვეული წესები) · 429 Too Many Requests (სიხშირის ლიმიტი).
5
5xx — სერვერის შეცდომა
მოთხოვნა კარგი იყო; ჩავარდა სერვერი. იდემპოტენტური ზმნები უსაფრთხოდ მეორდება.
+
  • 500 Internal Server Error — ყოვლისმომცველი ბაგი; არასოდეს გაუშვათ სტეკ-ტრეისი სხეულში.
  • 502 Bad Gateway · 503 Service Unavailable — ზემოთ მდგარი სერვისი ჩავარდა ან გადატვირთულია; 503 დააწყვილეთ Retry-After-თან.
  • 504 Gateway Timeout — ზემოთ მდგარმა სერვისმა დროულად ვერ უპასუხა.

ავტომატიზაციისთვის ყველაზე მნიშვნელოვანი გაყოფა: 4xx = ნუ გაიმეორებთ, გაასწორეთ მოთხოვნა; 5xx = სერვერი ჩავარდა, იდემპოტენტური ზმნის გამეორება ნორმალურია.

05 · რესურსების მოდელირება 5 წთ

URL-ები არსებითი სახელებია;
მეთოდები კი — ზმნები.

REST-ის მთავარი ხრიკი: ქმედება URL-ში ნუ ჩასვამთ. დაასახელეთ რესურსი და დანარჩენი HTTP-მეთოდს ათქმევინეთ, რა უნდა უყოს მას. ერთი თანმიმდევრული ფორმა ცვლის მორგებული ენდპოინტების მთელ ჯუნგლს.

REST — Representational State Transfer — თქვენს სისტემას მოდელირებს როგორც URL-ებით იდენტიფიცირებულ რესურსებს (საგნებს). მათ მდგომარეობას გადაადგილებთ წარმოდგენების (ჩვეულებრივ JSON-ის) გაცვლით, სტანდარტული მეთოდების გამოყენებით. ზმნა არასოდეს დგას გზაში — გზა მხოლოდ არსებით სახელს ასახელებს.
RPC URL-ში — ზმნა ყოველ ქმედებაზე
POST /createUser POST /getUser?id=42 POST /updateUserEmail POST /deleteUserById GET /listUsersByRoleAdmin // every action is a new endpoint to learn, // document, secure and cache separately.
რესურსი + მეთოდი — ერთი ფორმა, მრავალჯერ
POST /users // create GET /users/42 // read one GET /users?role=admin // filter the collection PATCH /users/42 // partial update DELETE /users/42 // remove // same nouns, predictable everywhere.

კოლექცია ინახავს ელემენტებს; ელემენტებს კი ქვეკოლექციები შეიძლება ჰქონდეთ. იგივე ექვსი მეთოდი მუშაობს ყველა დონეზე.

URL-ის კონვენციები, რომლებიც კარგად ბერდება

  • მრავლობითი არსებითი სახელები კოლექციებისთვის — /users, /orders — და არა /getUser.
  • იერარქია კუთვნილებისთვის — /users/42/orders იკითხება როგორც „42-ე მომხმარებლის შეკვეთები“.
  • query-სტრიქონი ფილტრაციის, დახარისხებისა და გვერდებად დაყოფისთვის — ?role=admin&sort=name&page=2 — და არა ახალი გზები.
  • პატარა ასოებით, დეფისებით, ბოლოში ზმნის გარეშე — /purchase-orders, არასოდეს /PurchaseOrders/create.

ჰგავს  საბუთების კარადას: უჯრები და საქაღალდეები არსებითი სახელებია; ის, რასაც აკეთებთ (შეიტანთ, წაიკითხავთ, გაანადგურებთ), თქვენ მიერ მოტანილი ქმედებაა.

06 · ჰედერები, შეთანხმება & ქეშირება 4 წთ

ჰედერებით მოთხოვნა და პასუხი
ერთმანეთს უთანხმდება.

სხეული დატვირთვაა; ჰედერები კი მის გარშემო შეკრული კონტრაქტია — რა ფორმატი, რა ავთენტიფიკაცია, რამდენ ხანს რჩება ახალი. ორი ნიმუში ყოველდღიურად იმართლებს თავს: კონტენტის შეთანხმება და ქეშირება.

კონტენტის შეთანხმება

კლიენტი ითხოვს; სერვერი შესაბამისად პასუხობს

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

// request — "I'd like JSON, in English" Accept: application/json Accept-Language: en // response — "here's what I'm giving you" Content-Type: application/json; charset=utf-8
ქეშირება

თქვით, რამდენად ახალია და როგორ გადამოწმდეს

Cache-Control ადგენს სიახლის ბიუჯეტს; ETag კი სხეულის ანაბეჭდია. ერთად ისინი კლიენტს აძლევენ საშუალებას, გამოტოვოს ჩამოტვირთვა, როცა არაფერი შეცვლილა.

// response — cache 5 min, here's the fingerprint Cache-Control: max-age=300 ETag: "v23-9af1" // next request — "only send if it changed" If-None-Match: "v23-9af1" // → 304, no body

კლიენტი თავის ETag-ს უკან აგზავნის; თუ ის ისევ ემთხვევა, სერვერი პასუხობს 304-ით, სხეულის გარეშე — თითქმის უფასო პასუხით.

რატომაა ეს ზმნაზე მიბმული

  • ნაგულისხმევად ქეშირებადია მხოლოდ უსაფრთხო მეთოდები (GET/HEAD) — სპეციფიკაცია ქეშს მათ შენახვას სწორედ იმიტომ რთავს, რომ ისინი მდგომარეობას არ ცვლიან.
  • წარმატებულმა PUT/PATCH/DELETE-მა ამ URL-ის ქეშირებული წარმოდგენა უნდა გააუქმოს.
  • პირობითი მოთხოვნები (If-Match) ასევე იცავს დაკარგული განახლებებისგან — უარყავით PUT, რომლის ETag მოძველებულია, 409 Conflict-ით.

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

07 · ინსტრუმენტები, API-სტილი 4 წთ

მეთოდები თეორიაა;
აი, ის ინსტრუმენტები, რომლებსაც შეეხებით.

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

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

API-კლიენტები — როგორ გააგზავნოთ მოთხოვნა ხელით

curl

ბრძანების ხაზის სამუშაო ცხენი

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

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

სრული გრაფიკული სახელოსნო

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

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

უფრო მსუბუქი, ლოკალური კლიენტი

ღია კოდის გრაფიკული კლიენტი, Postman-ზე მჭლე, REST-ისა და GraphQL-ის სრულფასოვანი მხარდაჭერითა და მარტივი OpenAPI-იმპორტით.

  • დადებითი — სუფთა, სწრაფი და სრულად ოფლაინ მუშაობს; შესანიშნავი GraphQL-გამოცდილება.
  • უარყოფითი — Postman-თან შედარებით უფრო მცირე ეკოსისტემა და ნაკლები გუნდური / თანამშრომლობის ფუნქციონალი.

როგორ ავირჩიო: curl — ავტომატიზაციისა და გამართვისთვის, Postman — როცა გუნდს დიდი, დოკუმენტირებული API უნდა გააზიაროს, Insomnia — როცა სწრაფი ლოკალური კლიენტი გინდათ ან GraphQL-ში ცხოვრობთ.

OpenAPI (მისი ძველი სახელია Swagger) დე-ფაქტო სტანდარტია API-სპეციფიკაციებისთვის: ერთი მანქანურად წასაკითხი ფაილი (YAML ან JSON), რომელიც ჩამოთვლის თქვენი API-ს ყოველ გზას, მეთოდს, შემავალ მონაცემსა და პასუხს. ერთხელ დაწერეთ და ინსტრუმენტები მისგან თავად აგენერირებენ ინტერაქტიულ დოკუმენტაციას, მზა კლიენტ-ბიბლიოთეკებს, მოკ-სერვერებსა და მოთხოვნის ვალიდატორებს — ისე, რომ აღწერა და რეალური API ერთმანეთს ვერ ასცდეს. დადებითი: ერთი ჭეშმარიტების წყარო, უამრავი უფასო ინსტრუმენტი. უარყოფითი: დიდი სპეციფიკაციის სიზუსტეში შენარჩუნებას ნამდვილი დისციპლინა სჭირდება.

API-სტილები — საერთო ფორმა

REST

რესურსები URL-ებზე

არსებითი სახელები გზაში, HTTP-მეთოდები ზმნების როლში — ზუსტად ის, რაზეც მთელი ეს საუბარი იყო. ვებ-API-ების უმეტესობის ნაგულისხმევი არჩევანი.

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

ერთი ენდპოინტი, ველებს თქვენ ითხოვთ

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

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

ტიპიზირებული გამოძახებები სერვისებს შორის

ბინარული, კონტრაქტზე დაფუძნებული სტილი (HTTP/2-ზე), სადაც სერვისის ტიპიზირებულ მეთოდებს იძახებთ — UserService.Get() — თითქმის ისე, როგორც ლოკალურ ფუნქციას.

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

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

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

სურათის წაკითხვა

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

ჰგავს  ლანჩის შეკვეთას: REST სამი ცალკე დახლია, GraphQL — ერთი მორგებული შეკვეთა, gRPC კი სამზარეულოსთან დადებული მუდმივი შეთანხმება.

08 · რეალური ენდპოინტის დიზაინი 3 წთ

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

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

არღვევს კონტრაქტს
GET /orders/cancel?id=88 // ✕ GET that mutates — caches & prefetch can fire it // ✕ verb in the URL, id in the query // ✕ returns 200 with { "error": "not allowed" } // ✕ retry on timeout → cancels again, maybe refunds twice
იცავს კონტრაქტს
POST /orders/88/cancellation Idempotency-Key: 7c1e-…-04 // ✓ a cancellation is a resource you create // ✓ → 201 Created, or 409 if already shipped // ✓ wrong owner → 403; missing order → 404 // ✓ idempotency-key makes the retry a no-op
1ზმნა სიმართლეს ამბობს. GET კითხულობს, დანარჩენები ცვლიან — არასოდეს დამალოთ ეფექტი უსაფრთხო მეთოდის უკან.
2იცოდეთ, რა არის უსაფრთხო და რა იდემპოტენტური. სწორედ ეს წყვეტს, რა შეუძლიათ თქვენს გამეორებებს, ქეშებსა და პროქსებს.
3აირჩიეთ სწორი სტატუს-კლასი. 2xx იმუშავა, 4xx გამომძახებელია, 5xx თქვენ ხართ — ავტომატიზაცია ამაზეა დამოკიდებული.
4დაამოდელირეთ არსებითი სახელები, არა ქმედებები. რესურსები URL-ში, ქცევა მეთოდში, ფილტრები query-სტრიქონში.
5დაეხმაროთ ქსელს, რომ დაგეხმაროთ. გულწრფელი სემანტიკა + ETag-ები + იდემპოტენტურობის გასაღებები უფასოდ გაძლევთ ქეშირებასა და უსაფრთხო გამეორებებს.

გააგრძელეთ

  • MDN HTTP reference — მეთოდები, სტატუს-კოდები, ჰედერები; ავტორიტეტული და უფასო.
  • RFC 9110 — HTTP Semantics — თავად სპეციფიკაცია, გასაკვირად წასაკითხი.
  • httpwg.org & http.cat — სამუშაო ჯგუფი და სტატუს-კოდები, რომლებიც ნამდვილად დაგამახსოვრდებათ.

ერთი წინადადება დასამახსოვრებლად

„URL არსებითი სახელია, მეთოდი კი — ზმნა; ორივემ სიმართლე უნდა თქვას.“

— მთელი საუბარი ერთ ხაზში

ცოდნის შემოწმება

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

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

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

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