Ποιες είναι οι κύριες στρατηγικές versioning API, και πώς κάνετε deprecate μια έκδοση;

Question

IT Interview Practice · Accepted Answer

Το versioning σας επιτρέπει να εξελίσσετε ένα API με **breaking changes** χωρίς να σπάτε τους υπάρχοντες clients. Υπάρχουν τρεις κύριες στρατηγικές, συν μια διαδικασία deprecation.

## Οι τρεις στρατηγικές

**1. URI versioning** — η έκδοση βρίσκεται στο path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Η πιο απλή και πιο ορατή· εύκολη στο routing, το caching, και το testing σε έναν browser. Μειονέκτημα: παραβιάζει τεχνικά το "το URI ταυτοποιεί έναν πόρο" (ο ίδιος user έχει τώρα δύο URLs). Αυτή είναι μακράν η πιο συνηθισμένη επιλογή (GitHub, Stripe ιστορικά).

**2. Custom header versioning** — η έκδοση ταξιδεύει σε ένα header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Κρατά τα URLs καθαρά αλλά είναι αόρατη σε έναν browser και δυσκολότερη στο caching.

**3. Media-type (content negotiation) versioning** — η έκδοση στο `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Η πιο "RESTful" (το URL του πόρου είναι σταθερό· μόνο η αναπαράστασή του γίνεται 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 changes χρειάζονται νέα έκδοση· προσθέστε τα non-breaking changes στην τρέχουσα.

## Διαδικασία deprecation

1. **Ανακοινώστε** με ημερομηνίες στο documentation και το changelog.
2. **Σηματοδοτήστε κατά το runtime** με headers ώστε οι clients να το αντιληφθούν προγραμματιστικά:
```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. **Παρακολουθήστε** τη χρήση της παλιάς έκδοσης και επικοινωνήστε με τους υπόλοιπους callers.
4. **Sunset** μόνο αφού η χρήση πέσει κοντά στο μηδέν.

## Γιατί έχει σημασία

Οι συνεντευξιαστές το ρωτούν για να δουν αν μπορείτε να μεγαλώσετε ένα API στην παραγωγή χωρίς να σπάσετε τους clients που εξαρτώνται από αυτό — μια πραγματική λειτουργική ανησυχία, όχι θεωρητική. Οι πιο δυνατές απαντήσεις κάνουν δύο διακρίσεις: πρώτον, ότι **οι περισσότερες αλλαγές είναι non-breaking** και δεν θα έπρεπε καν να πυροδοτούν αύξηση έκδοσης (οι προσθετικές αλλαγές πάνε στην τρέχουσα έκδοση), κρατώντας το versioning για γνήσια breaking changes· και δεύτερον, ότι η *στρατηγική* έχει λιγότερη σημασία από τη *διαδικασία* — ένα σαφές χρονοδιάγραμμα deprecation με headers `Deprecation`/`Sunset` και παρακολούθηση χρήσης είναι αυτό που πραγματικά προστατεύει τους καταναλωτές. Το URI versioning κερδίζει στην πράξη για την ορατότητα και την υποστήριξη εργαλείων του, αλλά το να γνωρίζετε τις ανταλλαγές (τα header και media-type κρατούν τα URLs σταθερά και είναι πιο RESTful, με κόστος την ανακαλυψιμότητα) δείχνει ότι κατανοείτε τον χώρο σχεδίασης παρά απλώς αντιγράφετε άκριτα το `/v1/`.

Οι τρεις στρατηγικές

Τι θεωρείται breaking

Διαδικασία deprecation

Γιατί έχει σημασία

Σχετικές ερωτήσεις