Esitystilan siirto, joka tunnetaan yleisesti nimellä REST, on arkkitehtoninen tyyli - joukko rajoituksia, joita käytetään HTTP: llä toimivien valtiottomien palvelujen toteuttamiseen. RESTful-sovellusliittymä on sellainen, joka noudattaa REST-rajoituksia. Voit rakentaa RESTful-sovellusliittymiä käyttämällä monia eri ohjelmointikieliä.
Taaksepäin yhteensopivuuden ylläpitäminen sovellusliittymän eri versioiden välillä on ensiarvoisen tärkeää varmistaa, että sovellusliittymäsi pysyy yhteensopivana kaikkien sitä käyttävien asiakkaiden kanssa. Tässä artikkelissa käsitellään keskustelua siitä, miten voit ylläpitää taaksepäin yhteensopivuutta RESTful-sovellusliittymissäsi.
API-yhteensopivuusesimerkki
Oletetaan, että sinulla on tuotannossa sovellusliittymä, jota eri asiakkaat käyttävät. Jos haluat nyt lisätä sovellusliittymään enemmän toimintoja, varmista, että vanhaa sovellusliittymää käyttävät asiakkaat voivat käyttää joko uutta tai vanhaa sovellusliittymää. Toisin sanoen, sinun on varmistettava, että sovellusliittymän nykyiset toiminnot pysyvät ennallaan, kun uusi toiminnallisuus lisätään.
API on taaksepäin yhteensopiva, jos asiakas (sovellus, joka on kirjoitettu kuluttamaan API: ta), joka voi toimia yhden API: n version kanssa, voi toimia samalla tavalla API: n tulevien versioiden kanssa. Toisin sanoen, sovellusliittymä on taaksepäin yhteensopiva julkaisujen välillä, jos asiakkaiden pitäisi pystyä toimimaan saumattomasti uuden sovellusliittymän version kanssa.
Ymmärretään tämä esimerkillä. Oletetaan, että sinulla on API-menetelmä nimeltä GetOrders, kuten alla olevassa koodinpätkässä näkyy.
[HttpGet][Reitti ("GetOrders")]
public IActionResult GetOrders (int clientId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
palaa Ok (tulos);
}
GetOrders-toimintamenetelmä hyväksyy asiakastunnuksen ja tilaustunnuksen parametreiksi. Huomaa, että toinen parametri orderID on valinnainen. Yksityinen GetOrdersForCustomer-menetelmä on annettu alla.
yksityinen luettelo GetOrdersForCustomer (int customerId, int orderId){
// Kirjoita koodi tähän palauttaaksesi yhden tai useamman tilaustietueen
}
GetOrdersForCustomer-menetelmä palauttaa kaikki asiakkaan tilaukset, jos sille parametrina välitetty orderId on 0. Jos orderId ei ole nolla, se palauttaa yhden asiakkaalle annetun tilauksen, jonka asiakasId tunnisti argumenttina.
Koska GetOrders-toimintamenetelmän toinen parametri on valinnainen, voit vain välittää asiakkaan tunnuksen. Jos muutat GetOrders-toimintamenetelmän toista parametria pakolliseksi, API: n vanhat asiakkaat eivät voi enää käyttää API: ta.
[HttpGet][Reitti ("GetOrders")]
public IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(asiakastunnus, tilaustunnus);
palaa Ok (tulos);
}
Ja juuri näin voit rikkoa sovellusliittymän yhteensopivuuden! Seuraava osio käsittelee parhaita käytäntöjä, joita voidaan soveltaa API-taaksepäin yhteensopivuuden parantamiseksi.
API-yhteensopivuusvinkit
Nyt kun tiedämme, mistä ongelmassa on kyse, miten voimme suunnitella sovellusliittymämme suositellulla tavalla? Kuinka voimme varmistaa, että RESTful-sovellusliittymämme on taaksepäin yhteensopiva? Tässä osassa luetellaan parhaita käytäntöjä, joita tältä osin voidaan noudattaa.
Varmista, että yksikön testit läpäisevät
Sinulla pitäisi olla testejä, jotka varmistavat, että toiminnallisuus on ehjä uuden sovellusliittymän julkaisun kanssa. Testit on kirjoitettava siten, että ne eivät onnistu, jos yhteensopivuusongelmia on taaksepäin. Ihannetapauksessa sinulla tulisi olla testipaketti API-testausta varten, joka epäonnistuu ja hälyttää, kun API: n taaksepäin yhteensopivuudessa on ongelmia. Voit myös liittää CI / CD-putkistoon automaattisen testipaketin, joka tarkistaa taaksepäin tapahtuvan yhteensopivuuden ja varoittaa rikkomuksista.
Älä koskaan muuta HTTP-vastauskoodien käyttäytymistä
Älä koskaan muuta HTTP-vastauskoodien käyttäytymistä sovellusliittymässäsi. Jos sovellusliittymä palauttaa 500, kun se ei pysty muodostamaan yhteyttä tietokantaan, sinun ei pitäisi muuttaa sitä 200: ksi. Vastaavasti, jos palautat HTTP 404: n poikkeuksen tapahtuessa ja asiakkaasi käyttävät tätä ja vastausobjektia tunnistamaan, mikä meni väärin, tämän API-menetelmän muuttaminen palauttamaan HTTP 200 rikkoo taaksepäin yhteensopivuuden kokonaan.
Älä koskaan muuta parametreja
Vältä luomasta uutta versiota sovellusliittymästä, kun teet vain pieniä muutoksia, koska se saattaa olla ylivoimainen. Parempi lähestymistapa on lisätä parametreja API-menetelmiin uuden käyttäytymisen sisällyttämiseksi. Samalla tavalla sinun ei pitäisi poistaa parametreja API-menetelmästä tai muuttaa parametria valinnaisesta pakolliseksi (tai päinvastoin), koska nämä muutokset rikkovat API: n ja API: n vanhat asiakkaat tai kuluttajat eivät enää voi toimimaan API: n kanssa.
Versio API: sta
API: n versiointi on hyvä käytäntö. Versiointi auttaa tekemään sovellusliittymästäsi joustavamman ja mukautuvamman muutoksiin pitäen samalla toiminnallisuutensa ennallaan. Se auttaa myös hallitsemaan koodin muutoksia paremmin ja palauttamaan vanhan koodin helpommin, jos uusi koodi aiheuttaa ongelmia. Sinulla on oltava eri versio RESTful-sovellusliittymästä jokaisen tärkeän julkaisun yhteydessä.
Vaikka REST ei tarjoa mitään erityisiä ohjeita sovellusliittymän versiosta, voit päivittää sovellusliittymän kolmella eri tavalla: määrittämällä versiotiedot URI: ssä, tallentamalla versiotiedot mukautetun pyynnön otsikkoon ja lisäämällä versiotiedot HTTP Accept -ohjelmaan otsikko. Vaikka versiointi voi auttaa sinua ylläpitämään sovellusliittymääsi, sinun tulee välttää yrittämästä ylläpitää monia sovellusliittymän versioita toistuvien julkaisujen merkitsemiseksi. Tästä tulee nopeasti hankalaa ja haitallista.
Muut sovellusliittymän parhaat käytännöt
Älä koskaan muuta API: n pää-URL-osoitetta tai muokkaa olemassa olevia kyselymerkkijonoparametreja. Mahdolliset lisätiedot tulisi lisätä valinnaisena parametrina API-menetelmään. Varmista myös, että valinnaisia tai pakollisia elementtejä, jotka välitetään sovellusliittymälle tai palautetaan sovellusliittymältä, ei koskaan poisteta.
Muutokset RESTful-sovellusliittymään ovat väistämättömiä. Ellet noudata parhaita käytäntöjä ja varmista, että sovellusliittymä on taaksepäin yhteensopiva, tekemäsi muutokset voivat rikkoa sovellusliittymän yhteensopivuuden nykyisten asiakkaiden kanssa. Tuotannossa olevan sovellusliittymän, jota useat asiakkaat käyttävät, tulisi aina olla taaksepäin yhteensopiva julkaisujen välillä.
