Većina API kvarova nisu kvarovi algoritama. To su trenuci trenja: klijent ne može utvrditi koje je polje obavezno, poruka o pogrešci ne nudi sljedeći korak, ponovni pokušaj stvara dvostruku naplatu ili „mala” promjena baze podataka neprimjetno pokvari mobilno izdanje koje je još uvijek u upotrebi.

Dizajn API-ja usmjeren na ljude tretira te trenutke kao prvoklasna arhitektonska pitanja. Potrošač može biti drugi razvojni programer, frontend aplikacija, integracijski partner ili usluga koju održava netko tko nije sudjelovao u izvornoj raspravi o dizajnu. U svakom slučaju, API je sučelje proizvoda. Njegova se kvaliteta mjeri ne samo propusnošću i ispravnošću, nego i time koliko ga ljudi mogu koristiti sigurno i s pouzdanjem.

Počnite od korisnikova zadatka, a ne od popisa krajnjih točaka

Katalog krajnjih točaka može izgledati uredno, a ipak od pozivatelja zahtijevati previše rada. Dizajniranje oko ljudske namjere znači započeti sa zadatkom: izraditi narudžbu, pregledati kupca, ažurirati postavke dostave ili oporaviti se od neuspjelog zahtjeva. Resursi i HTTP metode i dalje su vrijedni alati, ali trebali bi služiti zadatku, a ne postati ideologija.

Na primjer, API za izradu narudžbi trebao bi jasno prikazati važne odluke. Pozivatelj mora znati koje su vrijednosti prihvaćene, koje poslužitelj izračunava, jesu li cijene mjerodavne i što se događa ako isti zahtjev stigne dvaput. Skrivanjem tih odluka iza nejasnih naziva polja ili implicitnih pravila složenost se prebacuje na svakog klijenta.

Učinite ugovor očekivanim

Dosljednost je čin empatije. Upotrebljavajte isti stil imenovanja među resursima, datume prikazujte u jednom dokumentiranom formatu i primjenjujte paginaciju na isti način gdje god se vraćaju zbirke. Klijent ne bi trebao morati pamtiti da jedna krajnja točka upotrebljava page i per_page, dok druga upotrebljava offset i limit bez jasnog razloga.

• Upotrebljavajte imenice koje odgovaraju poslovnom jeziku koji korisnici već razumiju.
• Vraćajte stabilne identifikatore i razlikujte ih od oznaka za prikaz.
• Razlikujte nedostajuće vrijednosti od praznih vrijednosti kada je ta razlika važna.
• Dokumentirajte zadane vrijednosti, ograničenja i nuspojave uz polja koja ih pokreću.
• Neka oblici odgovora budu predvidljivi, osobito za pogreške i paginirane rezultate.

Predvidljivost ne znači kruti minimalizam. Odgovor može uključivati korisne poveznice, informacije o statusu ili metapodatke o provjeri valjanosti kada ti detalji pomažu pozivatelju dovršiti posao. Provjera je jednostavna: uklanja li ova informacija dodatni zahtjev, nagađanje ili razgovor s podrškom?

Pogreške bi nekome trebale pomoći da se oporavi

HTTP statusni kôd nužan je, ali rijetko dovoljan. Kôd 422 klijentu govori da provjera valjanosti nije uspjela; ne govori koje je polje neispravno, zašto je neispravno ili može li ga pozivatelj ispraviti. Koristan odgovor na pogrešku zadržava strojno čitljiv kôd, a istodobno pruža jasno i sigurno objašnjenje.

{
  "error": {
    "code": "validation_failed",
    "message": "Zahtjev sadrži neispravna polja.",
    "fields": {
      "email": ["Unesite valjanu adresu e-pošte."],
      "items.0.quantity": ["Količina mora biti najmanje 1."]
    }
  }
}

Nemojte izlagati tragove stoga, SQL poruke ni internu topologiju usluga. Ti detalji nisu djelotvorni za potrošača i mogu otkriti informacije o implementaciji. Interno zabilježite dijagnostički kontekst, odgovoru pridružite identifikator zahtjeva i timovima za podršku omogućite pouzdan način povezivanja prijavljene pogreške s dokazima na strani poslužitelja.

Neuspjesi također trebaju namjernu semantiku. Neispravno oblikovan zahtjev ne bi trebao izgledati kao privremeni prekid rada. Odgovor o ograničenju broja zahtjeva trebao bi klijentima reći kada mogu pokušati ponovno ako API može pružiti tu informaciju. Vremensko ograničenje mora se pažljivo razmotriti: poslužitelj je možda dovršio operaciju iako pozivatelj nije primio odgovor.

Dizajnirajte ponovne pokušaje prije nego što ih produkcija nametne

Mreže otkazuju na načine koje aplikacijski kôd ne može u potpunosti kontrolirati. Veze se zatvaraju, proxyji prekoračuju vremensko ograničenje, a klijenti pokušavaju ponovno nakon što izgube odgovor. Za operacije koje nešto stvaraju ili naplaćuju, ponovni pokušaji bez idempotentnosti ljudski su problem prerušen u problem distribuiranih sustava: netko na kraju mora objasniti i ispraviti duplikate.

Ključ idempotentnosti klijentu omogućuje izraziti da ponovljene predaje predstavljaju jednu namjeravanu radnju. Poslužitelj pohranjuje ključ s prikladnim opsegom i vraća izvorni rezultat za naknadne odgovarajuće zahtjeve. Precizno razdoblje zadržavanja i pravila podudaranja zahtjeva odluke su o proizvodu, ali moraju biti dokumentirani. Ponovna upotreba ključa s drukčijim podacima zahtjeva ne bi trebala neprimjetno proizvesti nepovezan rezultat.

POST /v1/orders HTTP/1.1
Idempotency-Key: 9d8b2f0a-unique-client-key
Content-Type: application/json

{"customer_id":"cus_123","items":[{"sku":"book-42","quantity":1}]}

Idempotentnost nije zamjena za transakcije, ograničenja jedinstvenosti ili pažljive prijelaze stanja. U PHP backendu aplikacijski sloj može koordinirati zahtjev, ali baza podataka trebala bi provoditi ključne invarijante. Ako se dva radnika natječu za rezervaciju iste zalihe, prijateljska metoda kontrolera sama po sebi nije posljednja linija obrane.

Verzionirajte zbog promjene, a ne zbog ceremonije

Svaki se API razvija. Pitanje je razvija li se na način koji potrošačima omogućuje namjernu prilagodbu. Aditivne promjene obično je lakše prihvatiti od uklanjanja ili promjena značenja, ali čak i novo polje može biti ometajuće ako klijenti imaju krhke pretpostavke o objektima odgovora.

Prije promjene ugovora utvrdite stvarne potrošače i njihovu toleranciju na promjene. Obavijesti o zastarijevanju, vodiči za migraciju i realno prijelazno razdoblje dio su implementacije, a ne dokumentacijski zadaci za odgađanje. Ako novo ponašanje mijenja značenje, izričita granica verzije može biti jasnija od zbirke oznaka čije interakcije nitko ne može pouzdano objasniti.

Migracije baze podataka zaslužuju istu suzdržanost. Uvođenje kôda koji očekuje novi stupac prije nego što stupac postoji može završiti neuspjehom; uklanjanje starog stupca dok starije instance aplikacije još rade može jednako lako završiti neuspjehom. Sigurniji obrazac je proširiti, migrirati, zatim suziti:

1. Dodajte novi element sheme u migraciji kompatibilnoj sa starijim verzijama.
2. Uvedite kôd koji prema potrebi može čitati staru i novu reprezentaciju.
3. Popunite podatke unatrag ili ih migrirajte radom koji se može pratiti i ponovno pokrenuti.
4. Premjestite sve potrošače na novo ponašanje.
5. Uklonite staru putanju tek nakon što se više ne upotrebljava.

Operativna jasnoća dio je sučelja

Docker i automatizacija implementacije mogu uslugu učiniti reproducibilnom, ali je ne čine automatski razumljivom. Spremnik bi trebao primati konfiguraciju putem izričitih postavki okruženja ili upravljanih tajni, zapisivati strukturirane zapise u standardni izlaz i jasno ne uspjeti kada potrebna ovisnost nije dostupna. Izbjegavajte tretirati ponovno pokretanje spremnika kao univerzalnu strategiju oporavka; ponovljena pokretanja mogu prikriti lošu migraciju, iscrpljeni skup veza ili nevaljanu konfiguraciju.

Performanse zaslužuju istu leću usmjerenu na ljude. Optimizirajte rad koji korisnici stvarno doživljavaju: spore krajnje točke za popise, dugotrajne izvoze, skupe provjere ovlaštenja i upite baze podataka koji rastu s količinom podataka. Mjerite prije promjene arhitekture. Predmemorija može poboljšati latenciju, ali također stvara pravila poništavanja i očekivanja o zastarjelim podacima koja pozivatelji možda trebaju razumjeti.

U PHP aplikacijama neka pitanja prijenosa, pravila domene i detalji postojanosti budu dovoljno odvojeni da se svako može testirati i mijenjati bez povlačenja ostalih za sobom. Kontroler bi trebao prevesti HTTP zahtjev u aplikacijsku radnju, a ne postati jedino mjesto na kojem postoje poslovne invarijante. Jasne granice olakšavaju razvoj API-ja jer ugovor nije zapleten sa svakim upitom i detaljem okvira.

Trajno pitanje dizajna

API usmjeren na ljude ne obećava da će integracija biti bez napora. Stvarni sustavi imaju dozvole, neuspjehe, asinkroni rad i sukobljene zahtjeve. Obećava nešto korisnije: teški dijelovi su vidljivi, dosljedni i moguće ih je riješiti.

Pri dizajniranju sljedeće krajnje točke zapitajte se što će sposobnom razvojnom programeru trebati u 2 sata ujutro tijekom incidenta. Može li razumjeti odgovor? Može li sigurno pokušati ponovno? Može li utvrditi je li promjena kompatibilna? Može li pratiti neuspjeh bez nagađanja? Ako je odgovor da, API je nadišao puko izlaganje algoritma. Postao je sučelje kojem ljudi mogu vjerovati.