REST API

História

REST je skratka pre Re presentational S tate T ransfer protokol. Roy Fielding definoval REST vo svojej dizertačnej práci v roku 2000.

Čo je to REST API?

REST bol vyvinutý s cieľom poskytnúť jednotné rozhranie pre server

  • Identifikácia zdrojov
  • Manipulácia so zdrojmi
  • Vlastné popisné správy
  • Používanie Hypermedia ako motora stavu aplikácie (HATEOS)

Osvedčené postupy

Základy

Metóda || //api.co/v2/cars || //api.co/v2/cars/1234

  • ZÍSKAŤ || Zoznam všetkých automobilov || Vyzdvihnite jednotlivé auto
  • POST || Vytvorte nové auto || Chyba
  • PUT || Vymeňte zbierky automobilov || Vymeňte auto za id 1234

    s novým

  • ODSTRÁNIŤ || Vymazať všetky autá || Vymazať auto s ID 1234

Všimnite si, že zatiaľ čo operácie PUT môžu generovať ID klient alebo server

Podstatné mená sú dobré Slovesá sú zlé

  • Používať podstatné mená sa odkazovať zdroje, ako je cars, fruitsatď.
  • Používajte slovesá na deklarácie akcií convertMilesToKms,getNutritionalValues

Jednotné alebo množné číslo?

Na vyhlásenie používajte správnu gramatiku

Vyhnúť sa/person/145

Preferovať/people/154 Predpokladajme, že vrátite 154. osobu zo zoznamu ľudí

Prípady použitia

Použite kohokoľvek z nižšie uvedených vzorov a buďte dôslední!

Štýly prípadu Príklad UpperCamelCase //api.fintech.cp/DailyTransactions/TodaylowerCamelCase //api.fintech.cp/dailyTransactions/todaysnake_case//api.fintech.cp/daily_transactions/today

Vzťahy a zdroje

  • Zdroje môžu mať one-to-many, many-to-many, many-to-onevzťahy atď. Mapovanie je správne, je veľmi dôležité.

Mapovanie one-to- many

Napríklad Tickets/145/messages/4naznačuje vzťah medzi mnohými medzi ticketsa messages. Význam 1lístka má Nsprávy. Správa nie je samostatným zdrojom. Nemôžeš mať /messages/4.

Mapovanie mnohých k mnohým

Napríklad /usergroups/345/users/56navrhuje zvoliť 345. skupinu používateľov a získať používateľa s ID 56. Jeden používateľ však môže byť vo viacerých, usergroupstj /usergroups/209/users/56je tiež platný. V takom prípade teda na oddelenie depedantného zdroja usersdo samostatného koncového bodu, ako je napríklad /users/56zabezpečenie a prepojenie zdroja v/usergroups/209/users/56

Parametre API

  • CESTA : požadovaná pre prístup k prostriedku Napr/cars./fruits
  • Parametre dotazu : voliteľné filtrovanie zoznamu Napr/cars?type=SUV&year=2010
  • Text : Logika špecifická pre zdroje. Pokročilý vyhľadávací dopyt. Niekedy to môže mať dopyt aj telo.
  • Hlavička : Malo by obsahovať globálne údaje alebo údaje o celej platforme. Napr. Kľúčové parametre API, šifrované kľúče pre autorizáciu, informácie o type zariadenia, napr. Mobilný alebo stolný počítač alebo koncový bod, dátový typ zariadenia, napr. Xml alebo json. Na komunikáciu týchto parametrov použite hlavičku

Stavové kódy HTTP

Používajte správne stavové kódy

CodesMeaning1xxRequest prijatá a pochopená. 2xx Akcia požadovaná klientom bola prijatá, pochopená a vyžiadaná. 3xxClient musí na splnenie požiadavky podniknúť ďalšie kroky. Väčšina z týchto stavových kódov sa používa pri presmerovaní adresy URL. 4xx Určené pre situácie, keď sa zdá, že chybu spôsobil klient. 5xx Server nesplnil požiadavku.

Trochu viac na 2xx !

  • Vytvorilo sa 201 zdrojov. POST/carsby mal vrátiť protokol HTTP 201 vytvorený slocationhlavičkou, v ktorom sa uvádza, ako pristupovať k prostriedku, naprlocation.api.com/cars/124V hlavičke

202 - prijaté

Toto použite, ak je úloha obrovská. Povedzte klientovi, že prijal požiadavku a bude / je spracovaný / spracovaný Nevráti sa žiadne užitočné zaťaženie

204 - Žiadny obsah

Používa sa pri odstránení. DELETE cars/124Vráti žiadny obsah. Môže sa však tiež vrátiť, 200 OKak má API v úmysle odoslať odstránený zdroj na ďalšie spracovanie.

Nebezpečné zdroje 5xx !

  • 500 interná chyba servera
  • 504 Časový limit brány. Server nedostal včasnú odpoveď

Menej známy 4xx naznačuje, že odovzdávate nesprávny parameter. Môže odovzdať aj nesprávne informácie. Napr

DELETE /cars/MH09234

vráti 4xxalebo správuExpecting int car id /car/id got string car/MH09234