API odstupanja rijetko dolaze s dramatičnom najavom. Počinju kao preimenovano polje, neobavezni filtar, pravilo paginacije koje se neprimjetno mijenja ili nizvodna usluga koja počinje vraćati novi statusni kôd. Svaka promjena zasebno izgleda mala. S vremenom integracijski kôd pretvaraju u skup obrambenih zakrpa čije izvorne pretpostavke više nisu vidljive.

Odgovor nije zauvijek zamrznuti svako sučelje. Stabilni API-ji su važni, ali sustavi se moraju razvijati. Korisniji je cilj projektirati za anticipativnu evoluciju: oblikovati granice, ugovore i prakse implementacije tako da očekivane promjene budu jeftine, a nesigurne promjene očite.

Pretpostavite da će se ugovori mijenjati

API ugovor je više od rute i primjera JSON-a. Uključuje obavezna i neobavezna polja, ponašanje provjere valjanosti, redoslijed, paginaciju, autentikaciju, formate pogrešaka, ograničenja broja zahtjeva i operativna očekivanja poput vremenskih ograničenja. Klijenti ovise o svemu tome, uključujući pojedinosti koje nitko nije zapisao.

Zato “samo smo dodali polje” nije automatski bezopasno. Tolerantan klijent trebao bi ignorirati nepoznata polja, ali strogi validator sheme, generirani model ili preslikavač baze podataka može ih odbiti. Slično tome, promjena enuma može pokvariti potrošače koji su pretpostavili iscrpan popis vrijednosti.

Započnite razlikovanjem aditivnih promjena od promjena koje prekidaju kompatibilnost. Aditivne promjene obično mogu koegzistirati s postojećim klijentima. Promjene koje prekidaju kompatibilnost zahtijevaju put migracije.

• Dodavanje neobaveznog svojstva odgovora obično je aditivno.
• Dodavanje obaveznog svojstva zahtjeva prekida kompatibilnost za postojeće pozivatelje.
• Preimenovanje ili promjena značenja polja prekida kompatibilnost, čak i kada njegov tip ostaje isti.
• Promjena zadanih postavki paginacije može prekinuti kompatibilnost kada se klijenti oslanjaju na potpune skupove rezultata.
• Zamjena poznatog odgovora o pogrešci generičkim može pokvariti i ponašanje klijenta i mogućnost nadzora.

Ta klasifikacija nije birokracija. Ona određuje je li dovoljna uobičajena implementacija ili je potrošačima potreban promišljen prijelaz.

Postavite antikorupcijski sloj na rubu

Pozadinske aplikacije postaju krhke kada transportni podaci teku izravno u poslovnu logiku i modele trajne pohrane. Kontroler koji dekodira JSON, prosljeđuje ga usluzi i pohranjuje ga kakav jest učinio je vanjsku reprezentaciju dijelom domene.

Umjesto toga, prevodite na granici. U PHP-u DTO zahtjeva ili preslikavač ulaza može provjeriti javni ugovor i konstruirati naredbu usmjerenu na domenu. Domena tada radi s konceptima koje posjeduje, a ne s nazivima koji su slučajno odabrani u HTTP podacima.

final class CreateSubscriptionInput
{
    public function __construct(
        public readonly string $customerId,
        public readonly string $planCode,
    ) {}
}

function mapCreateSubscription(array $payload): CreateSubscriptionInput
{
    if (!isset($payload['customer_id'], $payload['plan'])) {
        throw new InvalidArgumentException('customer_id and plan are required');
    }

    return new CreateSubscriptionInput(
        customerId: (string) $payload['customer_id'],
        planCode: (string) $payload['plan'],
    );
}

Kada javni API kasnije prihvati plan_code, preslikavač može podržavati oba naziva tijekom prijelaza, dok sloj usluge ostaje nepromijenjen. To je uska, namjerna odluka o kompatibilnosti, a ne propusnost koja se širi cijelom aplikacijom.

Isto načelo vrijedi pri korištenju API-ja trećih strana. Njihov odgovor odmah pretvorite u internu reprezentaciju. Ne dopustite da nazivi polja dobavljača, vrijednosti koje mogu biti null ili rječnik statusa postanu pretpostavke u cijeloj vašoj bazi koda.

Verzionirajte ponašanje, a ne samo URL-ove

Verzioniranje URL-a poput /v1/orders korisno je kada vam je potreban jasno odvojen ugovor. Ono nije zamjena za planiranje kompatibilnosti. Verzionalizirani krajnji endpoint i dalje može odstupati ako se njegova semantika promijeni bez dokumentacije, testova ili komunikacije s potrošačima.

Dajte prednost aditivnoj evoluciji unutar glavne verzije. Uvedite novo neobavezno polje prije nego što ga učinite obaveznim. Dodajte novi endpoint kada operacija ima bitno drukčije ponašanje. Zadržite staro ponašanje dovoljno dugo da stvarni klijenti prijeđu na novo. Novu glavnu verziju rezervirajte za promjene koje ne mogu sigurno koegzistirati.

Praktičan postupak zastarijevanja ima četiri dijela:

1. Dokumentirajte zamjenu i točnu razliku u ponašanju.
2. Izložite jasan signal zastarijevanja tamo gdje to podržavaju konvencije vašeg API-ja.
3. Mjerite preostalu upotrebu stare putanje ili polja.
4. Odredite datum uklanjanja tek nakon što postoji vjerodostojan put migracije.

Nemojte koristiti obavijest o zastarijevanju kao zamjenu za nadzor. Ako ne možete utvrditi koriste li potrošači još uvijek endpoint, nagađate o prekidima. Metrike zahtjeva, strukturirani zapisnici i identifikatori klijenata, gdje je prikladno, timu pružaju dokaze za sigurnu odluku o uklanjanju.

Neka se baze podataka razvijaju postupno

Promjene sheme baze podataka čest su izvor API odstupanja jer se izdanja aplikacije i migracije sheme ne događaju uvijek u istom trenutku. Siguran obrazac je proširi, migriraj, sažmi.

Najprije proširite shemu bez poništavanja valjanosti trenutačne aplikacije: dodajte nullable stupac, novu tablicu ili indeks. Zatim implementirajte kôd koji zapisuje novu reprezentaciju i može čitati i stare i nove oblike. Popunite postojeće podatke u kontroliranim skupinama. Tek nakon što je nova putanja uspostavljena trebate nametnuti ograničenja ili ukloniti staru strukturu.

Na primjer, promjena jednog tekstualnog polja shipping_address narudžbe u strukturirane stupce adrese ne bi trebala početi brisanjem starog stupca. Dodajte nove stupce, zapisujte u oba oblika uz provjeru rezultata, popunite starije retke, prebacite čitanja i uklonite naslijeđeno polje u kasnijem izdanju.

Dvostruki zapisi uvode privremenu zabrinutost oko dosljednosti, stoga razdoblje održavajte kratkim i nadziranim. Odlučite koja je reprezentacija mjerodavna, bilježite nepodudarnosti i učinite ponašanje ponovnih pokušaja idempotentnim. Ponovni pokušaj nakon vremenskog ograničenja ne smije stvoriti dvije pretplate, dva računa ili dvije proturječne verzije istog zapisa.

Testirajte kompatibilnost kao značajku proizvoda

Jedinični testovi dokazuju lokalnu logiku; ne dokazuju da API ostaje upotrebljiv postojećim klijentima. Dodajte testove usmjerene na ugovor oko granice. Za API-je pružatelja provjerite može li klijent raščlaniti reprezentativne odgovore, uključujući neobavezna polja, nedostajuća polja tamo gdje su dopuštena i nepoznate enum vrijednosti. Za API-je koje objavljujete testirajte dokumentirane primjere zahtjeva i odgovora u odnosu na pokrenutu aplikaciju.

Ugovori vođeni potrošačima mogu pomoći kada postoji više internih potrošača, ali zahtijevaju disciplinu. Ugovor treba izražavati stvarnu ovisnost, a ne zamrznuti slučajni detalj implementacije. Pregledavajte ga jednako pažljivo kao produkcijski kôd.

Testirajte i putanje neuspjeha. Potvrdite što se događa kada je ovisnost spora, nedostupna ili vraća neispravne podatke. Osigurajte da su ponovni pokušaji ograničeni, vremenska ograničenja izričita, a pogreške preslikane u stabilan javni format. Kompatibilnost uključuje i način na koji sustav otkazuje.

Implementirajte za reverzibilnost

Docker i automatizirana isporuka čine implementacije ponovljivima, ali ponovljivost nije automatski i reverzibilnost. Izbjegavajte izdanja koja zahtijevaju da se svaki spremnik prebaci odjednom. Tijekom postupne implementacije stare i nove instance aplikacije mogu istodobno posluživati promet. Obje moraju razumjeti aktivnu shemu baze podataka i sve poruke koje se već nalaze u redovima.

Zastavice značajki vrijedne su kada odvajaju implementaciju od aktivacije. Najprije implementirajte podršku za novi ugovor, omogućite je ograničenoj publici, pratite pogreške i latenciju, a zatim proširite. Zastavica je najkorisnija kada je njezino isključeno stanje i dalje testirana, održiva putanja — a ne zaboravljena grana koja je pokvarena mjesecima.

Arhitektura koja predviđa evoluciju ne uklanja API odstupanja. Ona odstupanje pretvara iz hitnog slučaja u uobičajen inženjerski rad: prepoznajte ugovor, očuvajte kompatibilnost tamo gdje je važna, promatrajte stvarnu upotrebu i uklonite staro ponašanje tek kada je sustav spreman. API koji se najlakše održava nije onaj koji se nikada ne mijenja. To je onaj koji se može mijenjati bez da se svaki potrošač boji sljedećeg izdanja.