რომელია მთავარი API versioning-ის სტრატეგიები და როგორ deprecate-ავ version-ს?

Question

IT Interview Practice · Accepted Answer

Versioning საშუალებას გაძლევთ API განავითაროთ **breaking change-ებით** არსებული client-ების გატეხვის გარეშე. არსებობს სამი მთავარი სტრატეგია, პლუს deprecation-ის პროცესი.

## სამი სტრატეგია

**1. URI versioning** — version არის path-ში.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
ყველაზე მარტივი და ხილული; ადვილი route-ისთვის, cache-ისთვის და ბრაუზერში ტესტისთვის. მინუსი: ტექნიკურად ის არღვევს „URI აიდენტიფიცირებს resource-ს" (იმავე user-ს ახლა ორი URL აქვს). ეს ყველაზე გავრცელებული არჩევანია (GitHub, Stripe ისტორიულად).

**2. Custom header versioning** — version header-ში მოგზაურობს.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
ინახავს URL-ებს სუფთად, მაგრამ უხილავია ბრაუზერში და უფრო რთულია cache-ისთვის.

**3. Media-type (content negotiation) versioning** — version `Accept`-ში.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
ყველაზე „RESTful" (resource URL სტაბილურია; მხოლოდ მისი representation-ია versioned), მაგრამ ყველაზე ძნელად მისადგომი მომხმარებლისთვის.

## რა ითვლება breaking-ად

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
მხოლოდ breaking change-ს სჭირდება ახალი version; non-breaking ცვლილებები დაამატეთ მიმდინარეს.

## Deprecation-ის პროცესი

1. **გამოაცხადეთ** თარიღებით docs-ში და changelog-ში.
2. **მიეცით სიგნალი runtime-ზე** header-ებით, რომ client-ებმა პროგრამულად შეამჩნიონ:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **დააკვირდით** ძველი version-ის გამოყენებას და დაუკავშირდით დარჩენილ caller-ებს.
4. **Sunset** მხოლოდ მას შემდეგ, რაც გამოყენება ნულთან ახლოს ჩამოვა.

## რატომ არის ეს მნიშვნელოვანი

ინტერვიუერები ამას სვამენ იმის სანახავად, შეგიძლიათ თუ არა API-ს გაზრდა production-ში მასზე დამოკიდებული client-ების გატეხვის გარეშე — რეალური საოპერაციო საზრუნავი, არა თეორიული. ყველაზე ძლიერი პასუხები ორ განსხვავებას აკეთებენ: პირველი, რომ **ცვლილებების უმეტესობა non-breaking-ია** და საერთოდ არ უნდა გამოიწვიოს version bump (დანამატი ცვლილებები მიმდინარე version-ში მიდის), versioning-ს კი ჭეშმარიტად breaking ცვლილებებისთვის ინახავს; და მეორე, რომ *სტრატეგია* ნაკლებად მნიშვნელოვანია, ვიდრე *პროცესი* — ნათელი deprecation-ის ვადა `Deprecation`/`Sunset` header-ებით და გამოყენების monitoring-ით არის ის, რაც რეალურად იცავს მომხმარებლებს. URI versioning პრაქტიკაში იმარჯვებს თავისი ხილულობითა და tooling-ის მხარდაჭერით, მაგრამ ტრეიდ-ოფების ცოდნა (header და media-type URL-ებს სტაბილურად ინახავს და უფრო RESTful-ია, აღმოჩენადობის ხარჯზე) აჩვენებს, რომ გესმით დიზაინის სივრცე და არა უბრალოდ `/v1/`-ის ბრმად კოპირება.

სამი სტრატეგია

რა ითვლება breaking-ად

Deprecation-ის პროცესი

რატომ არის ეს მნიშვნელოვანი

დაკავშირებული კითხვები