streamalism.org

1. Problem

Razvoj REST API-ja je težak problem - onaj za koji je dostupno mnogo opcija. Ovaj članak razmatra neke od ovih mogućnosti.

2. Što je u ugovoru?

Prije svega moramo odgovoriti na jedno jednostavno pitanje: Koji je ugovor između API-ja i Klijent?

2.1. URI-ovi dio ugovora?

Prvo razmotrimo URI struktura REST API-ja - je li to dio ugovora? Trebaju li klijenti stavljati oznake, tvrde kodove i općenito se oslanjati na URI-je API-ja?

Ako je to slučaj, interakciju Klijenta s REST uslugom više ne bi pokretala sama Usluga, već ono što Roy Fielding poziva izvan benda informacija:

API REST treba unijeti bez prethodnog znanja izvan početnog URI-ja (oznake) i skupa standardiziranih vrsta medija koje odgovaraju prikladnoj publici ... Ovdje ovdje podrazumijevamo da informacije izvan opsega potiču interakciju umjesto hiperteksta.

Tako jasno URI nisu dio ugovora! Klijent treba znati samo jedan URI - ulaznu točku u API. Sve ostale URI-je treba otkriti tijekom konzumiranja API-ja.

2.2. Vrste medija dio ugovora?

Što je s informacijama o vrsti medija koje se koriste za predstavljanje resursa - jesu li to dio ugovora između Klijenta i Usluge?

Da bi uspješno koristio API, Klijent mora imati prethodno znanje o tim vrstama medija. Zapravo, definicija ovih vrsta medija predstavlja cijeli ugovor.

Stoga bi se REST služba trebala najviše usredotočiti:

API REST trebao bi potrošiti gotovo sav svoj opisni napor u definiranju vrsta medija koji se koriste za predstavljanje resursa i pokretanju stanja aplikacije ili u definiranju proširenih naziva relacija i / ili označavanja s omogućenim hipertekstom za postojeće standardne vrste medija.

Dakle Definicije vrste medija dio su ugovora i trebalo bi biti prethodno znanje za klijenta koji koristi API. Tu dolazi do standardizacije.

Sada imamo dobru ideju o ugovoru, prijeđimo na to kako se zapravo pozabaviti problemom s verzijama.

3. Opcije na visokoj razini

Razgovarajmo sada o pristupima na visokoj razini za izradu verzija REST API-ja:

• Izrada verzija URI-ja - verzija URI prostora pomoću indikatora verzije
• Izrada verzija medija - inačica Reprezentacija resursa

Kada predstavimo verziju u prostor URI-ja, prikazi resursa smatraju se nepromjenjivima. Dakle, kad u API treba uvesti promjene, treba stvoriti novi prostor URI-ja.

Na primjer, recimo da API objavljuje sljedeće resurse - korisnike i privilegije:

// host / v1 / users // host / v1 / privilegiji

Sada, uzmimo u obzir da je prelomna promjena u korisnika API zahtijeva uvođenje druge verzije:

// host / v2 / users // host / v2 / privilegiji

Kada inačicu Medijske verzije i proširimo jezik, prođemo kroz Pregovaranje o sadržaju na temelju ovog zaglavlja. API REST koristiće prilagođene vrste dobavljača MIME medija umjesto generičkih vrsta medija kao što su aplikacija / json. Umjesto URI-ja napravit ćemo inačicu ovih vrsta medija.

Na primjer:

===> GET / users / 3 HTTP / 1.1 Prihvatite: application / vnd.myname.v1 + json <=== HTTP / 1.1 200 OK Content-Type: application / vnd.myname.v1 + json {"user": {"name": "John Smith"}}

U ovom članku "Prilagođene vrste medija za API-je za odmor" potražite dodatne informacije i primjere u vezi s ovom temom.

Ono što je ovdje važno shvatiti je to klijent ne pretpostavlja o strukturi odgovora izvan onoga što je definirano u vrsti medija.

Zbog toga generičke vrste medija nisu idealne. Ovi ne pružaju dovoljno semantičkih podataka i prisiliti klijenta na upotrebu zahtijevaju dodatne savjete za obradu stvarnog prikaza resursa.

Izuzetak od toga je uporaba nekog drugog načina jedinstvenog prepoznavanja semantike sadržaja - poput XML sheme.

4. Prednosti i nedostaci

Sad kad imamo jasan koncept onoga što je dio Ugovora između Klijenta i Usluge, kao i pregled mogućnosti verzije API-ja na visokoj razini, razgovarajmo o prednostima i nedostacima svakog pristupa.

Prvi, uvođenje identifikatora verzije u URI dovodi do vrlo velikog otiska URI. To je zbog činjenice da će svaka prijelomna promjena u bilo kojem od objavljenih API-ja uvesti potpuno novo stablo reprezentacija za cijeli API. S vremenom to postaje teret za održavanje, ali i problem za klijenta - koji sada ima više mogućnosti na izbor.

Identifikatori verzije u URI-u SU također vrlo nefleksibilni. Ne postoji način da se jednostavno razvije API jednog resursa ili male podskupine cjelokupnog API-ja.

Kao što smo već spomenuli, ovo je pristup na sve ili ništa. Ako se dio API-ja premjesti na novu verziju, tada se cijeli API mora premjestiti zajedno s njom. To također čini nadogradnju klijenata s v1 na v2 velikim pothvatom - što dovodi do sporije nadogradnje i mnogo duljih razdoblja zalaska sunca za stare verzije.

HTTP predmemoriranje također je glavna briga što se tiče izrade verzija.

Iz perspektive proxy predmemorije u sredini, svaki pristup ima prednosti i nedostatke. Ako je URI verzija verzija, tada će predmemorija trebati zadržati više kopija svakog resursa - po jednu za svaku verziju API-ja. To opterećuje predmemoriju i smanjuje stopu pogodaka predmemorije jer će različiti klijenti koristiti različite verzije.

Također, neki mehanizmi za onesposobljavanje predmemorije više neće raditi. Ako je vrsta medija ona koja je verzija, tada i Klijent i Usluga moraju podržavati Vary HTTP zaglavlje kako bi naznačili da postoji više verzija koje se predmemoriraju.

Od perspektiva predmemoriranja klijenta međutim, rješenje koje inači vrstu medija uključuje malo više posla od onoga u kojem URI sadrže identifikator verzije. To je zato što je jednostavno lakše nešto predmemorirati kada je njegov ključ URL nego vrsta medija.

Završimo ovaj odjeljak definiranjem nekih ciljeva (izravno iz API Evolucije):

• sprečite kompatibilne promjene u imenima
• izbjegavajte nove glavne verzije
• vrši promjene unatrag kompatibilne
• razmislite o kompatibilnosti s naprijed

5. Moguće promjene API-ja

Dalje, razmotrimo vrste promjena REST API-ja - one su ovdje uvedene:

• promjene formata predstavljanja
• promjene resursa

5.1. Dodavanje u prikaz resursa

Dokumentacija formata za vrstu medija trebala bi biti dizajnirana imajući na umu kompatibilnost s vremenom. Točnije, klijent bi trebao zanemariti informacije koje ne razumije (što JSON radi bolje od XML-a).

Sada, dodavanjem informacija u Prikazu resursa neće se slomiti postojeći klijenti ako su ispravno implementirani.

Da nastavimo naš raniji primjer, dodavanjem iznos u predstavljanju korisnik neće biti velika promjena:

{"user": {"name": "John Smith", "amount": "300"}}

5.2. Uklanjanje ili promjena postojeće reprezentacije

Uklanjanje, preimenovanje ili općenito restrukturiranje podataka u dizajnu postojećih reprezentacija predstavlja ključnu promjenu za klijente. To je zato što oni već razumiju i oslanjaju se na stari format.

Tu dolazi do Pregovaranja o sadržaju. Za takve promjene, možemo dodati novu vrstu medija MIME dobavljača.

Nastavimo s prethodnim primjerom. Recimo da želimo razbiti Ime od korisnik u ime i prezime:

===> GET / users / 3 HTTP / 1.1 Prihvati: application / vnd.myname.v2 + json <=== HTTP / 1.1 200 OK Content-Type: application / vnd.myname.v2 + json {"user": {"firstname": "John", "lastname": "Smith", "amount": "300"}}

Kao takvo, ovo predstavlja nespojivu promjenu za Klijenta - koji će morati zatražiti novu Reprezentaciju i razumjeti novu semantiku. Međutim, prostor URI-a ostat će stabilan i to neće utjecati.

5.3. Glavne semantičke promjene

To su promjene u značenju Resursa, odnosa između njih ili onoga na što se karta nalazi u pozadini. Ovakve promjene mogu zahtijevati novu vrstu medija ili mogu zahtijevati objavljivanje novog, sestrinskog resursa uz stari i korištenje povezivanja kako bi se na njega ukazalo.

Iako ovo zvuči kao da se iznova koriste identifikatori verzije u URI-u, važna je razlika u tome što je novi resurs objavljuje se neovisno o bilo kojim drugim resursima u API-ju i neće rastaviti cijeli API u korijenu.

API REST trebao bi se pridržavati ograničenja HATEOAS. Prema tome, većinu URI-ja klijenti trebaju OTKRITI, a ne kodirati. Promjena takvog URI-ja ne bi se trebala smatrati nekompatibilnom promjenom. Novi URI može zamijeniti stari, a klijenti će moći ponovno otkriti URI i dalje funkcionirati.

Vrijedno je napomenuti da, iako je upotreba identifikatora verzije u URI-u problematična iz svih ovih razloga, nije ne-odmara u svakom slucaju.

6. Zaključak

Ovaj je članak pokušao pružiti pregled vrlo raznolikog i teškog problema razvija REST službu. Razgovarali smo o dvama uobičajenim rješenjima, prednostima i nedostacima svakog od njih te načinima obrazloženja ovih pristupa u kontekstu REST-a.

Članak završava iznošenjem razloga za drugo rješenje - izrada verzija medija dok ispituje moguće promjene RESTful API-ja.

Potpuna implementacija ovog vodiča može se naći u projektu GitHub.

7. Daljnje čitanje

Obično su ovi izvori za čitanje povezani u cijelom članku, ali u ovom slučaju jednostavno ima previše dobrih:

• • REST API-ji moraju biti hipertekstualni
  • API evolucija
  • Povezivanje za HTTP API
  • Strategije kompatibilnosti