გვითხარით REST API-ში PUT მეთოდზე.

მეთოდი PUT გამოიყენება რესურსის შექმნის ან განახლებისთვის მითითებულ URI-ზე.

ძირითადი მახასიათებლები:

• იდემპოტენტურობა: ერთსა და იმავე PUT მოთხოვნის მრავალჯერ შესრულება გამოიწვევს ერთსა და იმავე რესურსის მდგომარეობას სერვერზე (თუმცა სერვერის პასუხი შეიძლება განსხვავდებოდეს).
• სრული ჩანაცვლება: PUT მოთხოვნა აგზავნის სრულ ახალ წარმოდგენას რესურსზე, რომელიც შეცვლის არსებულს.
• შექმნა ან განახლება: თუ მითითებულ URI-ზე რესურსი არ არსებობს, PUT მას ქმნის. თუ არსებობს — განაახლებს. თუ რესურსი არ არსებობს, წარმატებული PUT მოთხოვნა იწვევს მის შექმნას და ჩვეულებრივ აბრუნებს სტატუსს 201 Created. არსებული რესურსის განახლება ჩვეულებრივ აბრუნებს 200 OK ან 204 No Content (თუ პასუხში სხეული არ არის).

ტიპიური გამოყენების სცენარები:

• სრული მომხმარებლის პროფილის განახლება.
• რესურსის შექმნა, თუ კლაიენტი განსაზღვრავს მის URI-ს.

PUT მოთხოვნის მაგალითი:

PUT /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "id": 123,
  "name": "ახალი სახელი",
  "email": "new.email@example.com"
}

სერვერი მიიღებს ამ მოთხოვნას და ან შექმნის მომხმარებელს id=123, ან სრულად შეცვლის ამ ID-ის მომხმარებლის ინფორმაციას მონაცემებით, რომლებიც მოცემულია მოთხოვნის სხეულში.

PUT განსხვავდება POST-დან შემდეგით:

• PUT გამოიყენება რესურსის განახლებისთვის ან შექმნისთვის ცნობილი URI-ზე, რომელიც განსაზღვრავს კლაიენტმა. POST გამოიყენება რესურსის შექმნისთვის, სადაც სერვერი განსაზღვრავს ახალი რესურსის URI-ს, ან სხვა მოქმედებებისთვის, რომლებიც არ შედიან სხვა HTTP მეთოდებში.
• PUT იდემპოტენტია, POST — არა. ერთსა და იმავე სხეულით მრავალჯერადი POST მოთხოვნები შეიძლება შექმნას რამდენიმე ერთნაირი რესურსი ან გამოიწვიოს სხვადასხვა გვერდითი ეფექტი.

შედარების სია PUT და POST-ის:

მახასიათებელი	PUT	POST
მიზანი	რესურსის შექმნა ან განახლება	რესურსის შექმნა, მონაცემების გაგზავნა
იდემპოტენტურობა	დიახ	არა
URI განსაზღვრა	კლაიენტით	სერვერით
რესურსზე გავლენა	სრულად შეცვლის ან შექმნის	ჩვეულებრივ დამატებს ან მოქმედებას ახორციელებს