როდესაც სოციალ ქსელში აქვეყნებთ პოსტს ან რომელიმე ვებ აპლიკაციაში ინფორმაცია შეგყავთ, სად მიდის თქვენს მიერ შეყვანილი ინფორმაცია? რა გზით იღებენ ეს აპლიკაციები თქვენს მიერ მიწოდებულ კონტენტს?
ეს ყველაფერი ხდება სპეციალური კავშირის მეთოდით რომელსაც API ეწოდება.
API – აკრონიმია და სრული დასახელება Application Programming Interface ანუ აპლიკაციის პროგრამირების ინტერფეისია. API-ს წყალობით სხვადასხვა სისტემები (როგორიცაა ინტერნეტ აპლიკაციები თქვენს სმარტფონზე) ამყარებენ კომუნიკაციას ერთმანეთთან და მიმოცვლიან ინფორმაციას.
როცა ფეისბუქზე პოსტს ანთავსებთ, თქვენი ტელეფონი ინფორმაციას უგზანვნის ფეისბუქის სერვერებს ამ პოსტის გამოსაქვეყნებლად. ფეისბუქი კი თავის მხრივ ეუბნება თქვენს ტელეფონს რომ ყველაფერი წარმატებით მიიღო და განათავსა თქვენს გვერდზე. ამ მიმოცვლის პროცესს API Call ეწოდება.
ინტერნეტ აპლიკაციების უმრავლესობა იყენებს “REST” API-ს, რაც მარტივად რომ თქვათ არის ერთერთი სტანდარტიზებული გზა კლიენტისთვის (თქვენი ტელეფონი, ლეპტოპიტ და ა.შ.) სერვერთან (Facebook, Google, ა.შ.) საურთიერთობოდ.
ფეისბუქის პოსტის მაგალითზე:
- თქვენი ტელეფონი აგზავნის ინფორმაციას (ტექსტი, ფოტო და ა.შ.) ფეისბუქის სერვერზე
- სერვერი იღებს ინფორმაციას, აწარმოებს ოპერაციას მასზე (მაგალითად პოსტავს თქვენს კედელზე) და უკან აგზავნის პასუხს თქვენს ტელეფონში
- თქვენი ტელეფონი (კლიენტი) ამ გზით იგებს ინფორმაცია წარმატებით გაიგზავნა თუ არა
ამას ეწოდება API flow ანუ ინფორმაციის მიმოდინება აპლიკაციის პროგრამირების ინტერფეისის საშუალებით. REST API-ს იყენებთ როცა აგზავნით იმეილს, ონლაინ კალენდარში ამატებთ ივენთს, იღებთ უახლეს ამინდის პროგნოზსს და ა.შ.
ინფორმაციის მიმოცვლა
ალბათ გაინტერესებთ Request-ი ანუ მოთხოვნა როგორ გამოიყურება.
Request-ს აქვს URL მისამართი და სპეციალური პარამეტრები ამ მისამართის ბოლოს. ამ გზით სერვერი იღებს დამატებით ინფორმაციას კლიენტის მოთხოვნის შესახებ. ალბათ თქვენთვის ნაცნობად გამოიყურება მსგავსი ფორმატი:
https://api.pcmania.ge/v2/create_article?title=სიახლე
სწორედ “title” არის ამ URL-ის პარამეტრი (key / გასაღები) რომლის საშუალებითაც ჩვენი სერვერი მიიღებს გაგზავნილი სტატიის სათაურს “სიახლე” რომელიც არის პარამეტრის მნიშვნელობა (value). პირველი პარამეტრი URL-ის მისამართში “?” კითხვის ნიშნით გამოიყოფა, ყოველი მომდევნო კი “&” სიმბოლოთი. როგორც მიხვდით ერთ მისამართში შეგვიძლია რამდენიმე პარამეტრი ჩავატიოთ.
https://api.pcmania.ge/v2/create_article?title=სიახლე&author=დევი&page=3
JSON ფორმატი
REST API-ს პასუხებს ზოგადად თან ახლავს გარკვეული დამატები ინფორმაცია – ეგრედ წოდებული “body” რაც მაგალითად გვამცნობს რა მოიქმედა სერვერმა მიღებული ინფორმაციით.
ბევრი თანამედროვე API იყენებს JSON ფორმატს რაც დაახლოებით შემდეგნაირად გამოიყურება:
{
"status": "published",
"date":"10/09/2000",
"author":"დევი ფირცხალაიშვილი",
"category":"ინტერნეტი",
"title":"ვებ 2.0 რევოლუცია",
}
JSON ფორმატი იგივე “JavaScript Object Notation” ერთქგვარი ჩანაწერის სტანდარტია დამატებითი ინფორმაციის მიმოცვლისათვის. სიტყვა “JavaScript” არ მიიჩნიოთ მის ლიმიტაციას მხოლოდ ჯავასკრიპტის პროგრამირების ენასთან, ეს ფორმატი ფართოდაა გამოყენებული სხვა ენებში და სისტემებში.
JSON-ში შეგიძლიათ სხვადასხვა ტიპის ინფორამციის ჩატევა, მათ შორის რიცხვების, ტექსტური (string), ბულეანების (boolean), მწყობრის (array), ცნობარის (dictionary) და ა.შ.
{
"string":"სმარტფონი",
"number":"300",
"boolean": true,
"array": [A1, B2, C3],
"dictionary": {
"item":"კამერა",
"item 2":"ეკრანი",
}
}
როგორც შეატყეთ პარამეტრების მსგავსად აქაც არის გასაღები ანუ “key” და მნიშვნელობა ანუ “value” რომელიც ორწერტილით “:” არის გამოყოფილი. ცნობარი (dictionary)-ის მნიშვნელობა შეიძლება დამატებითი key:value ქვე-წყვილი იყოს.
CRUD მეთოდები
REST API მასში შეიცავს გარკვეულ მოქმედებებს ანუ HTTP პროტოკოლის მეთოდებს.
მთავარი მოქმედებებია:
Create - შექმნა ------- POST Read - წაკითხვა ------- GET Update - განახლება ------ PUT Delete - წაშლა ----- DELETE
ეს მოქმედებები ეხმარება სერვერს გაიგოს რა გვსურს მოვიმოქმედოთ კონკრეტული ინფორმაციის მიმართ. კრებითათ ეს მოდელი მოიხსენება როგორც CRUD.
როდესაც თქვენი ბრაუზერიდან ან ტელეფონიდან პოსტავთ სოციალურ ქსელზე, ამ დროს თქვენ აგზავნით Create მოთხოვნას სერვერზე რომელიც “POST”-ით აღინიშნება.
როგორც გახსოვთ მოთხოვნას აქვს URL მისამართი, გარკვეული პარამეტრები და დამატებით ინფორმაცია.
საერთო ჯამში მაგალითად რაიმე პოსტის გამოქვეყნება დაახლოებით ესე გამოიყურება:
POST https://api.pcmania.ge/v2/create_article?publish=true
{
"title":"გამოსაქვეყნებელი სტატიის სათაური"
"text":"სტატიის შიგთავსი"
}
როცა რაღაც კონკრეტულის წაკითხვა გვსურს, ამ დროს ფაქტობრივად სერვერზე არაფერს არ ვცვლით. ამ შემთხვევაში ვაგზავნით Read მოთხოვნას რომელიც სერვერისთვის “GET”-ით აღინიშნება. მაგალითად:
GET https://api.pcmania.ge/v2/articles?id=300
ალბათ უკვე ხვდებით რომ თუ რამის უკვე არსებულ პოსტში ჩასწორება ან მთლიანად ამ პოსტის წაშლა გვსურს, შესაბამისად განახლების ანუ Update (PUT) ან წაშლის ანუ Delete (DELETE) მოთხოვნას გავუგზავნით სერვერს. როგორ წაკითხვის მსგავსად, ამ ორის გაგზავნისას უნდა მივუთითოთ კონკრეტული პოსტის (ან რამე ჩანაწერის) საიდენტიფიკაციო ინფორმაცია.
POST https://api.pcmania.ge/v2/articles?id=300
{
"title":"ახალი სათაური"
"text":"შეცვლილი ტექსტი"
}
დაბოლოებები და API ვერსიები
ამ სპეციალურ URL მისამართებს რომელსაც ვამატებთ პარამეტრებს და რომლის საშუალებითაც ვწვდებით სერვერს და ვახორციელებთ ოპერაციებს, Endpoints ანუ დაბოლოებები ეწოდება. წინა მაგალითში მოცემული დაბოლოება იყო: https://api.pcmania.ge/v2/articles
თუ დააკვირდით, ყველა URL მისამართს და დაბოლოებას შუაში ქონდა “v2” რომელიც ხშირ შემთხვევაში მიუთიტებს ამ აპლიკაციის ინტერფეისის კონკრეტულ ვერსიას.
ვინაიდან ვებ აპლიკაციები თვიდან თვემდე ვითარდება და ახლდება დამატებითი ფუნქციებით, ყველა პარამეტრი და დამატებითი ინფორმაციის შიგთავსის სტრუქტურა (Key:Value წყვილები) ყოველთვის ერთი და იგივე არ რჩება. თუ რომელიმე მოძველებული კლიენტი (მაგ: ძველი სმარტფონი ძველი ფეისბუქის აპლიკაციით) ამ განახლებულ სერვერს მიაკითხავს, მას კვლავ უნდა შეეძლოს სერვერთან ურთიერთობა და ინფორმაციის მიმოცვლა შეფერხებების გარეშე.
ამიტომ API-ს გამოყენებისას მიღებულია გქონდეს მისი კონკრეტული ვერსიები. თუ მაგალითად პირველი ვერსია V1 იყო და შემდეგ ბევრი განახლებების და ცვლილებების მერე გახდა v2, ის ძველი v1 ინტერფეისი კვლავ ხელმისაწვდომი უნდა იყოს მოძველებული კლიენტებისათვის რომ შეუფერხებელი კავშირი არსებობდეს.
ზოგჯერ დაბოლოებებში ხდება რაღაც ცვლილებები (ახალი პარამეტრი ან ახალი ნაწილი დამატებით ინფორმაციაში) რაც ახალი ვერსიის მიღებას არ საჭიროებს. მაგალითად თუ სახელის, თარიღის და ტექსტის იქით პოსტს ასევე დაემატა გეოგრაფიული ლოკაცია, ამან ძველი კლიენტებისთვის დიდი პრობლემა არ უნდა გამოიწვიოს. ამას Backwards Compatible ანუ უკუ-თავსებადი ინტერფეისი ეწოდება.
მაგრან თუ სერვერიდან მოვხსენით მაგალითად თარიღების მიმოცვლა ან შევცვალეთ კონკრეტული ჩანაწერის იდენტიფიკატორის სახე, ამ შემთხვევაში მოგვიწევს ეს ცვლილება ახალი ვერსიის ინტერფეისში მოვაქციოთ. ამავდროულად კი ძველი ვერსიის ინტერფეისი კვლავ ხელმისაწვდომი იყოს.
რესურსები
თუ დააკვირდით ზემოთ მაგალითად მოცემულ მისამართში / დაბოლოებაში ვერსიის გარდა მოცემული იყო ინფორმაციის ტიპი “article”
https://api.pcmania.ge/v2/articles
დაბოლოების ეს კონკრეტული ნაწილი ეუბნება სერვერს თუ რომელ ჩანაწერებთან გვსურს ცვლილებების გაგზავნა. ამ შემთხვევაში დაბოლოება მიუთითებს რომ ვმუშაობთ სტატიების განყოფილებაში. ამ სპეციალურ “articles” ნაწილს ეწოდება რესურსი. ამას გარდა შეიძლება სხვა რესურსებთან ვმუშაობდეთ, როგორიცა ვებსაიტის გვერდები, დარეგისტრირებული მოხმარებლების სია ან სხვა.
თავსართები
თავსართები იგივე “Headers” კიდევ ერთი პატარა მაგრამ ძალიან მნიშვნელოვანი ნაწილია API-ს ინფორმაციის მიმოცვლისა. Header-ის საშუალებით REST API იღებს და აგზავნის დეტალებს თქვენი მოთხოვნების შესახებ.
მაგალითად ყველაზე ხშირად თავსართით გადაიგზავნება სპეციალური ავტორიზაციის კოდი, რომელიც ეუბნება სერვერს კონკრეტულად ვინ აგზავნის მოთხოვნებს. თუ თქვენი ავტორიზაციის კოდი შეესაბამება ადმინისტრატორის პრივილეგიებს, მაშინ სერვერი “გენდობათ” და შეასრულებს თქვენს ბრძანებებს.
ავტორიზაციის თავსართი შეიძლება ასე გამოიყურებოდეს:
POST https://api.pcmania.ge/v2/articles?id=300 Authorization: Bearer F7jmk867Dev
{
"title":"ახალი სათაური"
"text":"შეცვლილი ტექსტი"
}
სერვერებმა შეიძლება თავსართი გამოიყენონ თავიანთი პასუხის ტიპის ასაღწერად. მაგალითათ არსებობს კონტენტის ტიპის თავსართი (Content-Type header) რაც აღგვიწერს რა ტიპის შიგთავს აგაზვნის სერვერი თავის პასუხში:
Content-Type: application/json
{
"id":300,
"status":"published"
}
არსებობს უამრავი ტიპის თავსართები და ზოგიერთი სერვერი სპეციალურად გამოგონილ არასტანდარტულ ჰედერებსაც იყენებს.
სტატუსის კოდები
ალბათ ყველაზე კარგად ცნობილი ნაწილი API-სა არის სტატუს კოდები, რომელმაც პოპულარულ კულტურაშიც ჰპოვა ადგილი.
სტატუსის კოდები გვეხმარება გავიგოთ რა ტიპის პასუხს იძლევა სერვერი (მაგალითად წარმატებით მიიღო თუ არა ინფორმაცია).
ეს კოდებ სტანდარტიზებული ნომრებია რომელიც კლიენტს შეუძლია გამოიყენოს იმის გასაგებათ თუ რა ბედი ეწია მათ მიერ გაგზავნილ მოთხოვნას.
მაგალითად ალბათ თქვენთვისაც კარგად ცნობილია სტატუსის კოდი 404 (Error 404) რომელიც მიუთითებს რომ თქვენს გაგზავნილ მოთხოვნაში მითითებული დაბოლოება ვერ იქნა ნაპოვნი. თუ სტატუსის კოდი 401 მოგივიდათ, მაშინ თქვენი მოხმარებლის ავტორიზაციის პრობლემა გაქვთ და შესაბამისად სერვერი ვერ “გენდობათ” ბრძანებების შესასრულებლად.
ყოველდღიურად შეიძლება შემდეგი კოდები იხილოთ:
200 OK —- წარმატებული მოთხოვნა
201 CREATED —- ჩანაწერი შექმნილია
401 UNATHORIZED —- მოხმარებელი არ არის ავტორიზებული
403 FORBIDDEN —– არასაკმარისი დაშვება ამ კონკრეტულ რესურსზე
404 NOT FOUND —- რესურსი არ იქნა ნაპოვნი
500 INTERNAL ERROR —- სერვერის შეცდომა
სულ ესაა REST API-ის შესახებ ინფორმაცია შესავალის დონეზე. იმედია ზემოთ მოცემული ინფორმაცია გამოგადგებათ გაიგოთ როგორ მუშაობს ინტერნეტ აპლიკაციები და გააგრძელოთ ამ მეთოდოლოგიის შესწავლა.