REST API

ვებგვერდზე დინამიურობისთვის საჭიროა სერვერთან კომუნიკაცია. სერვერთან კომუნიკაცია შესაძლებელია ძირითად ორი გზით:

• HTTP/HTTPS მოთხოვნები
  • REST API - Front-End-ის (კლიენტის) მხარე უგზავნის HTTP მოთხოვნას (GET, POST, PUT, PATCH, DELETE) Back-end-ის (სერვერის) მხარეს, რომელიც აბრუნებს, მნიშვნელობას მეტწილადად JSON ან XML ფორმატით.
  • GraphQL - REST მიდგომის ალტერნატივა.
• WebSockets
  • ორმხრივი გზა კლიენტსა და სერვერს შორის კომუნიკაციისთვის, კარგია ისეთი აპლიკაციებისთვის სადაც საჭიროა სწრაფად და უწყვტად ინფორმაციის მიმოცვლა (ჩათი, შეტყობინებები და ა.შ).`

ამ სტატიაში განვიხილავთ REST API-ის ზოგად იდეას კლიენტის მხარეს.

რა არის REST API?

HTTP/HTTPS მოთხოვნებისთვის გამოიყენება REST API. REST (Representational State Transfer) არის არქიტექტურული პატერნი, რომელიც კლიენტსა და სერვერს შორის ინფორმაციის მიმოცვლის წესებსა აღწერს. API (Application Programming Interface) იშიფრება, როგორც აპლიკაციის პროგრამული ინტერფეისი, ანუ შუამავალი, რომელიც აღწერს სხვადასხვა მეთოდებსა და მნიშვნელობებს. მაშასადამე, REST API არის დიზაინის პატერნი ან მიდგომა, რომლითაც შესაძლებელია სტანდარტიზებულად ქსელში ინფორმაციის გადაცემა და გადმოცემა.

HTTP მოთხოვნების უმეტესობა სწორედ REST API-ით ხელმძღვანელობს, ამიტომ ხშირად ყველა HTTP API-ისა და სერვისებს მოიხსენებენ როგორც RESTful სერვისებს.

REST API-ში ძირითადად გამოიყენება შემდეგი HTTP მოთხოვნის მეთოდები:

• GET - მონაცემების მიღების მოთხოვნა.
• POST - მონაცემების გაგზავნის / ჩაწერის მოთხოვნა.
• PUT - მონაცემების სრულიად განახლების მოთხოვნა.
• PATCH - მონაცემების ნაწილობრივ განახლების მოთხოვნა.
• DELETE - მონაცემების წაშლის მოთხოვნა.

მოთხოვნას იწყებს კლიენტის მხარე და სერვერი აბრუნებს პასუხს.

GET

GET მოთხოვნა გამოიყენება ინფორმაციის მისაღებად. შეგვიძლია query პარამეტრებით დამატებითი ინფორმაცია მივაწოდოთ სერვერს თუმცა body-ს გაგზავნა არ შეგვიძლია. request body არის მოთხოვნაზე მიმაგრებული მონაცემები, რომელიც შეგვიძლია სერვერს გავუგზავნოთ.

მაგალითისთვის შეგვიძლია განვიხილოთ everrest-ის ერთ-ერთ მოთხოვნა: შემთხვევითი ციტატის მოთხოვნა.

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

POST

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

ამ შემთხვევაში სერვერს ვუგზავნით ტექსტს, რის მიხედვითაც სერვერი გამოგვიგზავნის QR კოდზე ინფორმაციას.

მაგალითად, გაგზავნილი ინფორმაცია:

{
  "text": "https://iswavle.com"
}

დაბრუნებული მნიშვნელობა:

{
  "text": "https://iswavle.com",
  "type": "png",
  "format": "base64",
  "errorCorrectionLevel": "M",
  "result": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIQAAACECAYAAABRRIOnAAAAAklEQVR4AewaftIAAAOjSURBVO3BQY4jSQIDQWdA//+ybx3mwFMAglI1Pb00iz+Y+cdhphxmymGmHGbKYaYcZsphphxmymGmHGbKYaYcZsphphxmymGmvPhQEn6Tyk0SblRuktBUbpLQVFoSfpPKJw4z5TBTDjPlxcNUnpSEd6i0JLQkNJWbJDxJ5UlJeNJhphxmymGmvPiyJLxD5R1JaCo3KjcqLQlN5UlJeIfKNx1mymGmHGbKi79MEprKTRLekYSm8jc5zJTDTDnMlBf/51RaEprKTRKayn/ZYaYcZsphprz4MpU/SRJuVFoSblQ+ofInOcyUw0w5zJQXD0vCv0mlJaGptCS8Q6UloancJOFPdpgph5lymCkvPqTyJ1NpSWgq36TyX3KYKYeZcpgp8QcfSEJTaUl4ksonknCj8qQkPEnlmw4z5TBTDjPlxYdUWhJuVG6S0FRuknCjcqPSktBU3pGEptKS0FTekYSm8qTDTDnMlMNMiT/4oiTcqLQk3KjcJOFGpSXhSSotCTcqLQlNpSXhRuUTh5lymCmHmRJ/8KAkNJWWhHeovCMJT1JpSXiHyk0Smso7ktBUPnGYKYeZcpgpLx6m8qQkNJWWhKbSktBUWhKaSkvCjUpLQktCU3lHEn7TYaYcZsphpsQffCAJNyotCU2lJaGptCQ0lX9TEm5UWhKaSktCU2lJaCpPOsyUw0w5zJQXD1NpSWgqNyotCe9IwidUbpLQVFoSWhJukvCJJDSVTxxmymGmHGbKiy9TaUm4UWkqLQk3Ki0JNyo3SbhJwo1KS8KNyo1KS8KTDjPlMFMOM+XFlyXhRqUl4UblHSotCe9QuUnCTRI+kYSm0lSedJgph5lymCnxB/9hSWgq70jCk1TekYQbld90mCmHmXKYKS8+lITfpNJUWhJuVJpKS8KNSkvCTRKayo1KS8I7VD5xmCmHmXKYKS8epvKkJNwkoam8Iwk3Kp9QeUcSmkpLQlN50mGmHGbKYaa8+LIkvEPl36TSkvCOJHxCpSWhqbQkNJVPHGbKYaYcZsqLv0wSmsqNyo1KS8InVFoSWhJukvBNh5lymCmHmfLiL5eEd6jcqDxJpSXhRqUl4UmHmXKYKYeZ8uLLVL5JpSWhqbQkNJWbJDSVloSm0pLwCZXfdJgph5lymCkvHpaE35SEmyR8QuVGpSXhSUn4TYeZcpgph5kSfzDzj8NMOcyUw0w5zJTDTDnMlMNMOcyUw0w5zJTDTDnMlMNMOcyUw0z5H/YQqQhLFYXqAAAAAElFTkSuQmCC"
}

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

PUT

PUT მოთხოვნა გამოიყენება მაშინ, როცა გვსურს ინფორმაციის სრული განახლება.

მაგალითისთვის, წარმოვიდგინოთ, რომ მონაცემთა ბაზაში გვაქვს ამ ობიექტისმაგვარი ინფორმაცია:

{
  "users": [
    {
      "name": "John",
      "lastName": "Doe",
      "email": "john@doe.com",
      "age": 50
    }
  ]
}

და დაგვჭირდა მისი ჩანაცვლება ამ მონაცემის სტრუქტურით:

{
  "users": [
    {
      "name": "James",
      "lastName": "Brown",
      "email": "feel@good.com",
      "age": 60
    }
  ]
}

PUT მოთხოვნა მოისაზრებს მთლიანად ობიექტის შეცვლას.

PATCH

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

DELETE

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

მოთხოვნის სტრუქტურა

HTTP პროტოკოლში თითოეულ მოთხოვნას გააჩნია სპეციალური ჰედერები (Headers).

ჰედერები შეიცავენ შემდეგ ინფორმაციას:

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

ჰედერები შეგვიძლია დავყოთ 3 კატეგორიად:

• General - ზოგადი:
  • Request URL: რომელ მისამართზე მიდის მოთხოვნა.
  • Request Method: მოთხოვნის მეთოდი (GET, POST და ა.შ).
  • Status Code: მოთხოვნის შესაბამისი სტატუს კოდი.
  • Remote Address: IP მისამართ, რასაც სერვერი დაინახავს.
  • Referrer Policy: რამდენი რეფერენტის ინფორმაცია უნდა იყოს განსაზღვრული მოთხოვნაში.
• Resposne Headers - სერვერის მხრიდან დაბრუნებული ჰედერის მნიშვნელობები, რომელიც განსაზღვრავს თუ როგორი სახით უნდა გამოიყენოს ეს ინფორმაცია კლიენტმა:
  • Content-Type: როგორი ტიპის ინფორმაცია არის გამოგზავნილი სერვერიდან (HTML, JSON თუ სხვა).
  • Content-Length: განსაზღვრავს დაბრუნებული მნიშვნელობის ზომას ბიტებში.
  • Date: რა დროს დამუშავდა მოთხოვნა სერვერის მხარეს.
  • Server: პროგრამული ნაწილი, რომელსაც სერვერი იყენებს მოთხოვნის დამუშავებისთვის.
  • Set-Cookie: სერვერის მხრიდან გამოგზავნილი ქუქის მნიშვნელობა, რომელიც კლიენტის მხარეს უნდა მოთავსდეს.
  • Cache-Control: ქეშირების მიდგომა, თუ რა ნაწილის შენახვა უნდა მოხდეს კლიენტის მხარეს.
  • ETag: ქეშირებისთვის გამოყენებული ინფორმაცია, რომელიც განსაზღვრავს უნიკალურ მაიდენტიფიცირებელ მნიშვნელობას.
  • Access-Control-Allow-Origin: განსაზღვრავს თუ რომელ დომეინებს აქვს წვდომა სერვერის ამ რესურსზე.
• Request Headers - კლიენტის მხრიდან გაგზავნილი ინფორმაცია, რომელიც სერვერს ეხმარება მოთხოვნის დამუშავებაში:
  • Host: დომეინის ძირეული ნაწილი, რომელსაც უკავშირდება
  • User-Agent: კლიენტის პროგრამა, რომელმაც გააგზავნა მოთხოვნა (მაგ: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36).
  • Accept: კონტენტის ტიპი, რომელსაც მიიღებს კლიენტი დასამუშავებლად (მაგ: text/html, application/json და სხვა).
  • Accept-Encoding: განსაზღვრავს კონტენტის ენკოდირებას, რომელიც შეუძლია კლიენტმა დაამუშავოს.
  • Accept-Language: განსაზღვრავს ენას, რომლის გამოყენებაც შეუძლია კლიენტს.
  • Authorization: კლიენტის მხრიდან გაგზავნილი ტოკენი, რომლის გამოყენებაც შეუძლია სერვერს კლიენტის იდენტიფიცირებისთვის.
  • Content-Type: ინფორმაციის ტიპი, რომელიც გაგზავნილი იქნება მოთხოვნის body-ში.
  • Content-Length: გაგზავნილი კონტენტის მოცულობა ბიტებში.
  • Cookie: ქუქის მნიშვნელობები, რომლებიც უნდა გაიგზავნოს.
  • Referer: მისამართი URL სახით თუ საიდანაც იგზავნება მოთხოვნა.
  • Origin: მოთხოვნის სრული მისამართი, პროტოკოლი და პორტი, საიდანაც იგზავნება მოთხოვნა.
  • Connection: განსაზღვრავს ქსელის ღიად დარჩენას მოთხოვნის დასრულებამდე.

ჰედერები თითოეულ მოთხოვნაზე შესაძლებელია იყოს განსხვავებული. ასევე შესაძლებელია ახალი, მორგებული (custom) ჰედერების შექმნაც.

სტატუს კოდი

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

სტატუს კოდები შეგვიძლია დავყოთ ხუთ კატეგორიად:

1. ინფორმაციული სტატუს კოდები (100 - 199).
2. წარმატებული სტატუს კოდები (200 - 299).
3. გადამისამართების სტატუს კოდები (300 - 399).
4. კლიენტის შეცდომების სტატუს კოდები (400 - 499).
5. სერვერის შეცდომების სტატუს კოდები (500 - 599).

ძირითადი სტატუს კოდები, რომლებსაც ხშირად შეხვდებით:

შეგიძლიათ, ყოველ სტატუს კოდს გაეცნოთ MDN-ზე, ან იხილოთ ალტერნატივები სახალისო ილუსტრაციებით:

• კატების მოყვარულთათვის.
• ძაღლების მოყვარულთათვის.

Network-ის ინსპექტორი

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

inspect-ის გახსნა შეიძლება ვებგვერდზე კონტექსტური მენიუზე დაკლიკებით (მაუსის მარჯვენა ღილაკით) და შემდგომ inspect-ის არჩევით ან მალსახმობით:

• Windows/Linux: CTRL Shift I ან F12
• macOS: Cmd Option I

Network-ის ტაბის გახსნის შემდგომ, შეგიძლიათ აირჩიოთ ნებისმიერი მოთხოვნა, სადაც მოთხოვნის შესახებ უფრო მეტ დეტალებს ნახავთ (Headers, Payload, Preview, Response, Initiator, Timing და სხვა).

შეჯამება

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