API დოკუმენტაციები

სერვერთან დაკავშირება მარტივია, როცა იცი რა მისამართზე გააგზავნო მოთხოვნა და რა სტრუქტურის პასუხს უნდა ელოდე. სერვერზე, ჩვეულებრივ, მუშაობს ბექ-ენდ (back-end) დეველოპერი, რომელიც ააგებს და მოგვაწვდის endpoint-ებს. Endpoint-ები ეს არის მისამართის დაბოლოებები, რომლებზეც კლიენტს (Front-End) შეუძლია გაგზავნოს მოთხოვნები, თუმცა საიდან უნდა გაიგოს ფრონტ-ენდ დეველოპერმა, რა ენდფოინთები გამოიყენოს?

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

დოკუმენტაციის ვებსაიტები

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

Swagger

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

Everrest-საც გააჩნია თავისი Swagger:

ვებგვერდზე ჩანს სხვადასხვა endpoint-ები, ყოველივე ეს დაგენერირებულია სერვერის მხარეს.

მაგალითისთვის დააკლიკეთ /shop/products/all-ის GET მოთხოვნას, შემდეგ Try it out-ს (შესაძლებელია სხვა ენაზე ეწეროს ინტერნაციონალიზაციიდან გამომდინარე). ველში ორი პარამეტრი გამოჩნდება, რომლებიც სურვილისამებრ შეგიძლიათ შეავსოთ, და დააწექით Execute-ს.

Execute-ზე დაკლიკების შემდეგ, გამოჩნდება მოთხოვნის და პასუხის დეტალები:

• Curl - ეს არის Command line ხელსაწყო, რომლითაც შესაძლებელია HTTP მოთხოვნების გაგზავნა. ამ შემთხვევაში ჩვენ გვაქვს მოთხოვნის აღწერა CURL-ის ფორმატით.
• Request URL - რომელი მისამართიდან მოვითხოვეთ ინფორმაცია.
• Server response - სერვერის მიერ დაბრუნებული ინფორმაცია:
  • Code - დაბრუნებული სტატუს კოდი სერვერიდან.
  • Response body - სერვერის მიერ დაბრუნებული მონაცემები.

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

Postman & Insomnia

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

Postman

Postman არის Swagger-ს მსგავსი აპლიკაცია, რომელიც გაძლევთ საშუალებას რომ მოთხოვნები აგზავნოთ კოდის გარეშე.

მოთხოვნის შექმნისა და გაგზავნისთვის:

1. აკლიკებთ new ღილაკს.
2. ირჩევთ http.
3. ირჩევთ სასურველი მოთხოვნის ტიპს.
4. ჩაწერეთ მისამართი, სადაც უნდა გაიგზავნოს მოთხვონა.
5. send ღილაკზე დაკლიკებით აგზავნით მოთხოვნას.

Insomnia

Postman-ის კარგი ალტერნატივა არის Insomnia. მისი გამოყენება არის თითქმის იდენტური.

აპლიკაციის ინსტალაციის შემდეგ:

1. შექმენით კოლექცია.
2. დააკლიკეთ + და აირჩიეთ HTTP Request.
3. ირჩევთ სასურველი მოთხოვნის ტიპს.
4. ჩაწერეთ მისამართი, სადაც უნდა გაიგზავნოს მოთხვონა.
5. send ღილაკზე დაკლიკებით აგზავნით მოთხოვნას.

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

Workspace

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