API нұсқалау дегеніміз не
API нұсқаларын басқару
API нұсқалау
API нұсқалау — бар клиенттер үшін артқа үйлесімділікті сақтай отырып, API өзгерістерін басқару тәжірибесі.
Нұсқалау стратегиялары
| Стратегия | Мысал | Сипаттама | |-----------|-------|-----------| | URL жолы | /api/v1/users | URL жолындағы нұсқа | | Query параметрі | /api/users?version=1 | Параметрдегі нұсқа | | Header | X-API-Version: 1 | Header-дегі нұсқа | | Content Type | Accept: application/vnd.api.v1+json | Media type нұсқасы |
Семантикалық нұсқалау
- Major (v1→v2) — бұзатын өзгерістер
- Minor (v1.1→v1.2) — жаңа мүмкіндіктер, артқа үйлесімді
- Patch (v1.1.0→v1.1.1) — қателерді түзету
Үздік тәжірибелер
- Барлық өзгерістерді құжаттау (changelog)
- Кем дегенде 2 нұсқаны қолдау
- Deprecation туралы алдын ала хабарлау
- Sunset header-ларын пайдалану
- Көшіру құралдарын беру
Жаңа нұсқа қашан қажет
- Өрістерді немесе endpoint-терді жою
- Жауап форматын өзгерту
- Параметр семантикасын өзгерту
- Аутентификацияны өзгерту