REST-sovellusliittymät

Historia

REST on lyhenne sanoista Re presentational S tate T ransfer Protocol. Roy Fielding määritteli REST väitöskirjassaan vuonna 2000.

Mikä on REST-sovellusliittymä?

REST kehitettiin tarjoamaan yhtenäinen käyttöliittymä

  • Resurssien tunnistaminen
  • Resurssien käsittely
  • Itsekuvaavat viestit
  • Hypermedian käyttäminen sovellustilan moottorina (HATEOS)

Parhaat käytännöt

Perusasiat

Menetelmä || //api.co/v2/cars || //api.co/v2/cars/1234

  • SAA || Luettele kaikki autot || Hae yksittäinen auto
  • POST || Luo uusi auto || Virhe
  • PUT || Korvaa autokokoelmat || Vaihda auto tunnuksella 1234

    uuden kanssa

  • POISTA || Poista kaikki autot || Poista auto, jonka tunnus on 1234

Huomaa, että PUT-toiminnot joko asiakas tai palvelin voivat luoda tunnuksia

Substantiivit ovat hyviä Verbit ovat huonoja

  • Käytä kielen viitata resursseja, kuten cars, fruitsjne
  • Käytä verbejä toimintailmoituksiin convertMilesToKms,getNutritionalValues

Yksikkö vai monikko?

Käytä ilmoituksessa oikeaa kielioppia

Välttää/person/145

Mieluummin/people/154 Oletetaan palata 154. henkilö lista ihmisistä

Käytä koteloita

Käytä mitä tahansa alla olevista malleista ja ole johdonmukainen!

Case StylesExample UpperCamelCase //api.fintech.cp/DailyTransactions/TodaylowerCamelCase //api.fintech.cp/dailyTransactions/todaysnake_case//api.fintech.cp/daily_transactions/today

Suhteet ja resurssit

  • Resursseja voi olla one-to-many, many-to-many, many-to-onesuhteet jne Mapping ne oikein on ratkaisevan tärkeää.

Yhden moniin kartoitus

Esimerkiksi Tickets/145/messages/4ehdottaa yhden ja monen välistä suhdetta ticketsja messages. Merkitys 1lipulla on Nviestejä. Viesti ei ole erillinen resurssi. Et voi /messages/4.

Monista moniin kartoitukseen

Esimerkiksi /usergroups/345/users/56ehdottaa 345. käyttäjäryhmän valitsemista ja käyttäjän hankkimista tunnuksella 56. Yksi käyttäjä voi kuitenkin olla useita, usergroupseli se /usergroups/209/users/56on myös kelvollinen. Tällöin poistetun resurssin erottamiseksi userserilliseksi päätepisteen kaltaiseksi /users/56ja resurssien linkittäminen sisään/usergroups/209/users/56

API-parametrit

  • PATH : vaaditaan resurssin käyttämiseen, esim/cars./fruits
  • Kyselyparametrit : valinnainen suodattaa luettelon esim/cars?type=SUV&year=2010
  • Runko : Resurssikohtainen logiikka. Ennakkohaku. Joskus sillä voi olla sekä kysely että runko.
  • Otsikko : Sen tulisi sisältää globaalia tai alustanlaajuista tietoa. Esim. API-avainparametrit, salatut avaimet todennusta varten, laitetyyppitiedot, esim. Mobiili tai työpöytä tai päätepiste, laitetietotyyppi, esim. Xml tai json. Käytä otsikkoa näiden parametrien välittämiseen

HTTP-tilakoodit

Käytä oikeita tilakoodeja

CodesMeaning1xxRequest vastaanotettu ja ymmärretty. 2xx Asiakkaan pyytämä toimi vastaanotettiin, ymmärrettiin ja pyydettiin. 3xxClientin on toteutettava lisätoimet pyynnön täyttämiseksi. Suurinta osaa näistä tilakoodeista käytetään URL-uudelleenohjauksessa. 4xxSuunniteltu tilanteisiin, joissa näyttää siltä, ​​että asiakas on aiheuttanut virheen. 5xx Palvelin ei täyttänyt pyyntöä.

Hieman enemmän 2xx !

  • 201 Resurssi luotu. POST/carspitäisi palata HTTP 201 luotulocationheader siitä, miten päästä resurssia Esimlocation:api.com/cars/124header

202 - Hyväksytty

Käytä tätä, jos tehtävä on valtava ajaa. Kerro asiakkaalle, että se on hyväksynyt pyynnön ja käsittelee / käsittelee / käsittelee hyötykuormaa ei palauteta

204 - Ei sisältöä

Käytetään poistettaessa Ei DELETE cars/124palauta sisältöä. Mutta voi myös palata, 200 OKjos API aikoo lähettää poistetun resurssin jatkokäsittelyä varten.

Vaaralliset 5xx- resurssit!

  • 500 sisäinen palvelinvirhe
  • 504 yhdyskäytävän aikakatkaisu. Palvelin ei saanut ajoissa vastausta

Vähemmän tunnettu 4xx ehdottaa, että välität väärän parametrin. Voi välittää myös väärää tietoa. Esim

DELETE /cars/MH09234

palaa 4xxtai viestiExpecting int car id /car/id got string car/MH09234