REST API'er

Historie

REST står for Re presentational S tate T ransfer protocol. Roy Fielding definerede REST i sin ph.d.-afhandling i 2000.

Hvad er en REST API?

REST blev udviklet til at give en ensartet grænseflade til

  • Identificering af ressourcer
  • Manipulation af ressourcer
  • Selvbeskrivende meddelelser
  • Brug af Hypermedia som motor i applikationstilstand (HATEOS)

Bedste praksis

Grundlæggende

Metode || //api.co/v2/cars || //api.co/v2/cars/1234

  • FÅ || Liste over biler || Hent en individuel bil
  • POST || Opret en ny bil || Fejl
  • PUT || Erstat bilsamlinger || Udskift bilen med id 1234

    med ny

  • SLET || Slet alle biler || Slet bil med id 1234

Bemærk, mens PUT-operationer kan enten klient eller server generere id'er

Substantiver er gode Verb er dårlige

  • Brug navneord til at henvise ressourcer som cars, fruitsetc.
  • Brug verb til handlingserklæringer convertMilesToKms,getNutritionalValues

Enkel eller flertal?

Brug korrekt grammatik til erklæring

Undgå/person/145

Foretrækker/people/154 Antag at returnere 154. person fra listen over personer

Brug sager

Brug nogen af ​​nedenstående mønstre og vær konsekvent!

Sagstilarter Eksempel på //api.fintech.cp/DailyTransactions/TodayUpperCamelCase //api.fintech.cp/dailyTransactions/todaylowerCamelCase snake_case//api.fintech.cp/daily_transactions/today

Forhold og ressourcer

  • Ressourcer kan have one-to-many, many-to-many, many-to-onerelationer mv Kortlægning dem korrekt er afgørende.

En-til-mange- kortlægning

Foreslår for eksempel Tickets/145/messages/4et-til-mange forhold mellem ticketsog messages. Betydning 1billet har Nbeskeder. Besked er ikke en enkeltstående ressource. Du kan ikke have /messages/4.

Mange til mange kortlægning

Foreslår f.eks. At /usergroups/345/users/56vælge den 345. brugergruppe og få brugeren med id 56. En bruger kan dog være i flere, usergroupsdvs. /usergroups/209/users/56er også gyldig. I sådanne tilfælde for at adskille depedantressourcen userstil et separat slutpunkt som /users/56og give ressourcekobling/usergroups/209/users/56

API-parametre

  • PATH : kræves for at få adgang til ressourcen f.eks/cars./fruits
  • Forespørgselsparametre : valgfrit filtrer listen f.eks/cars?type=SUV&year=2010
  • Body : Ressourcespecifik logik. Forespørgsel på forhåndssøgning. Nogle gange kan det have både forespørgsel og krop.
  • Overskrift : Skal indeholde globale data eller platformsdata. F.eks. API-nøgleparametre, krypterede nøgler til godkendelse, information om enhedstype f.eks. Mobil eller desktop eller slutpunkt, enhedsdatatype f.eks. Xml eller json. Brug header til at kommunikere disse parametre

HTTP-statuskoder

Brug korrekte statuskoder

Koder Betydning1xx Anmodning modtaget og forstået.2xxHandling, der blev anmodet om af klienten, blev modtaget, forstået og anmodet. De fleste af disse statuskoder bruges i URL-omdirigering.4xxIntended til situationer, hvor det ser ud til, at fejlen var forårsaget af klienten.5xxServeren kunne ikke opfylde en anmodning.

Lidt mere på 2xx !

  • 201 Ressource oprettet. POST/carsskal returnere HTTP 201 oprettet medlocationheader, der angiver, hvordan man får adgang til ressourcen, fxlocation:api.com/cars/124i header

202 - Accepteret

Brug dette, hvis opgaven er enorm at køre. Fortæl klienten, at den har accepteret anmodningen og vil / behandler / behandler Ingen nyttelast returneres

204 - Intet indhold

Brugt når slettet DELETE cars/124Returnerer intet indhold. Men kan også vende tilbage, 200 OKhvis API har til hensigt at sende den slettede ressource til videre behandling.

De farlige 5xx ressourcer!

  • 500 intern serverfejl
  • 504 Gateway timeout. Serveren modtog ikke rettidigt svar

Mindre kendt 4xx antyder, at du sender forkert parameter. Kan også videregive oplysninger, der er forkerte. F.eks

DELETE /cars/MH09234

returnerer 4xxeller meddelelseExpecting int car id /car/id got string car/MH09234