Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

api-versioning

/api-versioning

Wersjonuje API tak, by istniejący klienci działali mimo zmian kontraktu, z realnym procesem wygaszania.

Repozytorium
AI-SKILLS ↗
Licencja
MIT
Ostatnia zmiana repozytorium
05.09.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wersjonuje API tak, by istniejący klienci działali mimo zmian kontraktu, z realnym procesem wygaszania.

Oryginalny opis (EN)

Version APIs so existing clients keep working while the contract evolves, with a real sunset process. Use when choosing a versioning scheme or planning a breaking API change.

Jak działa

  1. Method
  2. Boundaries
Sekcje z nagłówków SKILL.md, w oryginale · 43 linii, 307 słów
Podgląd SKILL.md
---
name: api-versioning
description: Version APIs so existing clients keep working while the contract evolves, with a real sunset process. Use when choosing a versioning scheme or planning a breaking API change.
---

# API versioning

The best version strategy is needing versions rarely: evolve additively,
and when you must break, break loudly, once, with a long runway.

## Method

1. **Exhaust additive evolution first.** New optional fields, new
   endpoints, new enum values (documented as open sets) are not breaking.
   Removing, renaming, retyping, tightening validation, changing defaults
   or error codes are. Keep the taxonomy written down where reviewers see
   it (see api-change-management).
2. **Pick URL-path versioning unless you have a reason.** `/v1/orders`
   is visible in logs, testable in a browser, cacheable, and impossible
   to send by accident. Header/date-based versioning (Stripe-style
   pinning) is strictly better ergonomics at much higher implementation
   cost; choose it deliberately, not aspirationally.
3. **Version the whole surface, not per endpoint.** `/v1/orders` with
   `/v2/refunds` forces every client to carry a compatibility matrix.
   One version number, moved rarely.
4. **Keep old versions thin, not forked.** Implement vN-1 as a translation
   layer over the vN core (request/response adapters), or the old version
   stops getting bug fixes and becomes a second product.
5. **Run sunsets as a program.** Announce with dates; emit
   `Deprecation` and `Sunset` headers; instrument per-client version
   usage; contact the top consumers directly; brown-out (planned short
   outages) before the final cut. A version you cannot measure usage of
   is a version you can never remove.
6. **Give every response a version fingerprint.** Echo the resolved
   version in a header so support tickets and logs are unambiguous about
   what contract the client saw.

## Boundaries

- Internal APIs with deployable consumers usually need coordinated
  releases, not versions; versioning is for clients you do not control.
- Do not use versions as a feature-flag system; flags gate features
  inside a contract, versions change the contract.
- Event and webhook payloads version separately from the request API and
  are easier to break by accident; apply the same additive-only rule
  there (see webhooks-design).

Wersje

RepozytoriumWynikLicencja
Ta strona · Amey-Thakur/AI-SKILLS90MIT
TerminalSkills/skills100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
rrezartprebreza/spring-boot-skills100MIT
rrezartprebreza/spring-boot-skills100MIT
codewithmukesh/dotnet-claude-kit100MIT
ThibautBaissac/rails_ai_agents100MIT
tmj-90/gaffer90Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 2c966e2ed58c (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100versioning-and-evolution
    Projektuje strategię wersjonowania API: ścieżki URL albo nagłówki, wersje oparte na dacie, wycofywanie i nagłówki sunset.
  • 90change-policy
    Projektuje politykę wersjonowania i wycofywania API: reguły semver, terminy wygaszania i kanały komunikacji.
  • 100api-versioning-policy
    Definiuje politykę wersjonowania i deprecjacji API: schemat wersji, pisemna definicja zmiany łamiącej, okresy powiadomień, nagłówki Deprecation i Sunset, egzekwowanie w dniu wygaszenia i nadzór nad zmianami.
  • 90backend-api-versioning
    Prowadzi przejścia wersji API: wersjonowanie w adresie, w nagłówku lub przez negocjację treści, zmiany łamiące i wycofywanie endpointów.
  • 100api-versioning-helper
    Doradza w strategiach wersjonowania API, projektuje procesy wycofywania, generuje przewodniki migracji i klasyfikuje zmiany łamiące i niełamiące.
  • 90api-versioning-strategist
    Tworzy schemat wersjonowania API, politykę zmian łamiących i przyrostowych oraz harmonogram deprecjacji z publikowanym terminem wygaszenia i warstwami tłumaczącymi.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.