Waɗanne ne manyan dabarun versioning na API, kuma yaya kake deprecate ɗin version?

Question

IT Interview Practice · Accepted Answer

Versioning yana ba ka damar tasar da API da **breaking changes** ba tare da lalata clients da ke akwai ba. Akwai dabaru guda uku na gama-gari, tare da tsarin deprecation.

## Dabaru uku

**1. URI versioning** — version yana cikin path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Mafi sauƙi kuma mafi bayyana; mai sauƙin route, cache, da gwadawa a browser. Rashin dacewa: a fasaha yana keta "URI yana gane resource" (user iri ɗaya yanzu yana da URLs biyu). Wannan shi ne zaɓin da ya fi kowa nesa (GitHub, Stripe a tarihi).

**2. Custom header versioning** — version yana tafiya cikin header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Yana riƙe URLs tsaftace amma ba ya bayyana a browser kuma yana da wahalar cache.

**3. Media-type (content negotiation) versioning** — version a cikin `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Mafi "RESTful" (URL na resource yana da ƙarko; representation ɗinsa kaɗai ake yi wa version), amma mafi wahalar kaiwa ga masu amfani.

## Menene ake ƙidaya a matsayin 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 kaɗai ke bukatar sabon version; ƙara non-breaking changes zuwa na yanzu.

## Tsarin deprecation

1. **Sanar** da kwanakuna a cikin docs da changelog.
2. **Aika sigina a runtime** da headers don clients su lura ta hanyar shirye-shirye:
```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. **Sa ido** kan amfani da tsohon version kuma ka tuntuɓi masu kira da suka rage.
4. **Sunset** kawai bayan amfani ya sauka kusan sifili.

## Me ya sa yake da muhimmanci

Masu hira suna tambaya wannan don ganin ko za ka iya haɓaka API a production ba tare da lalata clients da suka dogara da shi ba — damuwa ta gaske ta aiki, ba ta ka'ida ba. Amsoshi mafi ƙarfi suna yin bambanci biyu: na farko, cewa **yawancin canje-canje non-breaking ne** kuma bai kamata su jawo version bump ko kaɗan ba (canje-canjen ƙari suna shiga version na yanzu), ana ajiye versioning ga breaking changes na gaske; na biyu, cewa *dabara* ba ta da muhimmanci kamar *tsari* — jadawali bayyananne na deprecation da headers na `Deprecation`/`Sunset` da sa ido kan amfani shi ne abin da ke kare masu amfani da gaske. URI versioning yana yin nasara a aikace saboda bayyanuwarsa da tallafin tooling, amma sanin trade-offs (header da media-type suna riƙe URLs da ƙarko kuma sun fi RESTful, a farashin gano-gani) yana nuna ka fahimci sararin ƙira maimakon kawai bin `/v1/` kamar cargo-cult.

Dabaru uku

Menene ake ƙidaya a matsayin breaking

Tsarin deprecation

Me ya sa yake da muhimmanci

Tambayoyi masu alaƙa