rest Handledning => Komma igång med vila

Anmärkningar

Det här avsnittet ger en översikt över vad vila är och varför en utvecklare kanske vill använda den.

Den bör också nämna alla stora ämnen inom vila och länka till relaterade ämnen. Eftersom dokumentationen för vila är ny kan du behöva skapa initialversioner av relaterade ämnen.

REST Översikt

REST står för RE presentational S tate T ransfer och myntades av Roy Fielding i sin doktorsavhandling Architectural Styles and the Design of Network-based Software Architectures . I den identifierar han specifika arkitektoniska principer som:

Adresserbara resurser: den viktigaste abstraktionen av information och data i REST är en resurs och varje resurs måste vara adresserbar via en URI.
Ett enhetligt, begränsat gränssnitt: användning av en liten uppsättning väl definierade metoder för att manipulera våra resurser.
Representationsorienterad: En resurs som refereras av en URI kan ha olika format och olika plattformar behöver olika format, till exempel behöver webbläsare HTML, JavaScript behöver JSON och Java-applikationer kan behöva XML, JSON, CSV, text osv. Så vi interagerar med tjänster använder representation av den tjänsten.
Kommunicera statslöst: statslösa applikationer är lättare att skala.
Hypermedia As the Engine Of Application State: låt våra dataformat driva tillståndsövergångar i våra applikationer.

Uppsättningen av dessa arkitektoniska principer kallas REST. Begreppen REST är inspirerade av HTTP. Roy Fielding som gav REST till oss är också en av författarna till HTTP-specifikationer.

Webbtjänster och RESTful Web Services är tjänster som utsätts för internet för programmatisk åtkomst. De är online-api som vi kan ringa från vår kod. Det finns två typer av ”stora” webbtjänster SOAP- och REST-webbtjänster.

RESTful Web Services : Webbtjänster som skrivs genom att tillämpa REST-arkitektoniska koncept kallas RESTful Web Services, som fokuserar på systemresurser och hur tillståndet för en resurs kan överföras via HTTP-protokoll till olika klienter.

Detta dokument är enbart fokuserat på RESTful webbtjänster så att vi inte kommer in på detaljerna i SOAP WS.

Det finns inga strikta regler när du utformar RESTful webbtjänster som

Ingen protokollstandard
Ingen kommunikationskanalstandard
Ingen tjänstdefinitionsstandard

Men SOAP har strikta regler för alla dessa. Alla SOAP-webbtjänster följer SOAP-specifikationen som dikterar vad alla SOAP-webbtjänster ska vara. Denna specifikation utvecklas och förvaltas av en kommitté och om SOAP WS inte ens följer en enda regel är den per definition inte SOAP.

Begrepp med RESTful Web Services

Det finns få riktlinjer som måste beaktas vid utformning / utveckling av RESTful api:

Resursbaserade platser / URI
Korrekt användning av HTTP-metoder
HATEOAS (Hypermedia As the Engine of Application State)

Det huvudsakliga tillvägagångssättet vid utvecklingen av RESTful API: er bör vara att göra API: n "så RESTful som möjligt".

RESTA över HTTP

REST är en protokollagnostisk arkitektur som föreslagits av Roy Fielding i hans avhandling (kapitel 5 är presentationen av REST), som generaliserar det beprövade konceptet för webbläsare som klienter för att avkoppla klienter i ett distribuerat system från servrar.

För att en tjänst eller API ska vara RESTful måste den följa givna begränsningar som:

Klient-server
Statslös
cacheable
Skiktat system
Enhetligt gränssnitt
- Resursidentifiering
- Resurser representation
- Självbeskrivande meddelanden
- hyper~~POS=TRUNC

Förutom de begränsningar som nämns i Fieldings avhandling måste REST-API: er i hans blogginlägg vara hypertekstdrivna , och Fielding klargjorde att bara att åberopa en tjänst via HTTP inte gör det RESTful . En tjänst bör därför också respektera ytterligare regler som sammanfattas enligt följande:

API: n ska följa och inte bryta mot det underliggande protokollet. Även om REST används via HTTP mestadels är det inte begränsat till detta protokoll.
Stark fokus på resurser och deras presentation via mediatyper.
Klienter bör inte ha initial kunskap eller antaganden om tillgängliga resurser eller deras returnerade tillstånd ( "typ" resurs ) i ett API, men lära dem på språng via utfärdade förfrågningar och analyserade svar. Detta ger servern möjlighet att flytta runt eller byta namn på resurser enkelt utan att bryta en klientimplementering.

Richardson Mognadsmodell

Richardson Maturity Model är ett sätt att tillämpa REST-begränsningar över HTTP för att få RESTful webbtjänster.

Leonard Richardson delade applikationer i dessa fyra lager:

Nivå 0: användning av HTTP för transporten
Nivå 1: användning av URL för att identifiera resurser
Nivå 2: användning av HTTP-verb och status för interaktioner
Nivå 3: användning av HATEOAS

Eftersom fokus ligger på representationen av en resurs tillstånd, uppmuntras att stödja flera representationer för samma resurs. En representation kan därför presentera en översikt över resurstillståndet medan en annan ger fullständig information om samma resurs.

Observera också att med tanke på Fielding-begränsningar är ett API effektivt RESTful endast när RMM: s tredje nivå har implementerats .

HTTP-förfrågningar och svar

En HTTP-begäran är:

Ett verb (aka metod), oftast ett av GET , POST , PUT , DELETE eller PATCH
En URL
Rubriker (par med nyckelvärde)
Valfritt ett organ (aka nyttolast, data)

Ett HTTP-svar är:

En status, oftast en av 2xx (framgångsrik) , 4xx (klientfel) eller 5xx (serverfel)
Rubriker (par med nyckelvärde)
Ett organ (aka nyttolast, data)

HTTP-verbs egenskaper:

Verber som har en kropp: POST , PUT , PATCH
Verber som måste vara säkra (dvs. som inte får ändra resurser): GET
Verber som måste vara idempotenta (dvs. som inte får påverka resurserna igen när de körs flera gånger): GET (nullipotent), PUT , DELETE

        body  safe  idempotent
GET      ✗     ✔     ✔
POST     ✔     ✗     ✗
PUT      ✔     ✗     ✔
DELETE   ✗     ✗     ✔
PATCH    ✔     ✗     ✗

Följaktligen kan HTTP-verb jämföras med CRUD-funktionerna :

C reate : POST
R EAD: GET
U PDATE : PUT , PATCH
D ELETE : DELETE

Observera att en PUT förfrågan ber kunderna skicka hela resursen med de uppdaterade värdena. För att delvis uppdatera en resurs kan ett PATCH verb användas (se Hur man uppdaterar en resurs delvis? ).

Vanliga HTTP-svarstatus

Framgång

201 (CREATED) : resurs har skapats
202 (ACCEPTED) : begäran accepterad, men processen pågår fortfarande
204 (INGEN INNEHÅLL) : begäran uppfyllt och inget ytterligare innehåll
Annars: 200 (OK)

Omdirigering

304 (NOT MODIFIED) : klienten kan använda den cache-version som den har av den begärda resursen

Klientfel

401 (UNAUTHORIZED) : en anonym begäran får åtkomst till ett skyddat API
403 (FORBIDDEN) : en autentiserad begäran har inte tillräckligt med rättigheter för att få åtkomst till ett skyddat API
404 (NOT FOUND) : resurs hittades inte
409 (CONFLICT) : resurstillstånd i konflikt (t.ex. en användare som försöker skapa ett konto med ett redan registrerat e-postmeddelande)
410 (GONE) : samma som 404, men resursen fanns
412 (PRECONDITION FAILED) : begäran försöker ändra en resurs som är i ett oväntat tillstånd
422 (OPROCESSABEL ENTITY) : begäran nyttolast är syntaktiskt giltig, men semantiskt felaktig (t.ex. ett obligatoriskt fält som inte har värderats)
423 (LOCKED) : resursen är låst
424 (FAILED PERSONAL) : begärda åtgärder berodde på en annan åtgärd som misslyckades
429 (För många förfrågningar ) : användaren skickade för många förfrågningar under en viss tid
Annars: 400 (DÅLIG FÖRSÖKNING)

Serverfel

501 (INTE IMPLEMENTERAD) : servern stöder inte den funktionalitet som krävs för att uppfylla begäran
503 (SERVICE UNAVAILABLE) : servern kan för närvarande inte hantera begäran på grund av tillfällig överbelastning eller schemalagt underhåll
507 (INSUFFICIENT LAGRING) : servern kan inte lagra den representation som krävs för att slutföra begäran
Annars: 500 (INTERN SERVERFEL)

anteckningar

Ingenting hindrar dig från att lägga till en kropp till felaktiga svar, för att göra avslaget tydligare för klienter. Till exempel är 422 (UNPROCESSABLE ENTITY) lite vag: svarorganet ska ange orsaken till att enheten inte kunde behandlas.

HATEOAS

Varje resurs måste tillhandahålla hypermedia till de resurser den är kopplad till. En länk består åtminstone av:

En rel (för rel ation, aka namn): beskriver relationen mellan huvud resurs och den länkade en (s)
En href : webbadressen som är inriktad på de / de länkade resurserna

Ytterligare attribut kan också användas för att hjälpa till med avskrivningar, innehållsförhandlingar etc.

Cormac Mulhall förklarar att klienten bör bestämma vilken HTTP-verb som ska användas baserat på vad den försöker göra . Vid tveksamhet bör API-dokumentationen ändå hjälpa dig att förstå tillgängliga interaktioner med all hypermedia.

Mediatyper

Mediatyper hjälper till att ha självbeskrivande meddelanden. De spelar den del av kontraktet mellan klienter och servrar, så att de kan utbyta resurser och hypermedier.

Även om application/json och application/xml är ganska populära mediatyper, innehåller de inte mycket semantik. De beskriver bara den övergripande syntaxen som används i dokumentet. Mer specialiserade mediatyper som stöder HATEOAS-kraven bör användas (eller utvidgas genom leverantörs mediatyper ), till exempel:

En klient berättar för en server vilka mediatyper den förstår genom att lägga till Accept rubriken till hans begäran, till exempel:

Accept: application/hal+json

Om servern inte kan producera begärd resurs i en sådan representation, returnerar den en 406 (INTE ACCEPTABLE) . Annars lägger den till mediatypen i rubriken Content-Type i svaret som innehåller den representerade resursen, till exempel:

Content-Type: application/hal+json

Statslös> statlig

Varför?

En tillförlitlig server innebär att klientsessionerna lagras i en serverinstans-lokal lagring (nästan alltid i webbserversessioner). Detta börjar vara ett problem när du försöker skala horisontellt : om du döljer flera serverinstanser bakom en belastningsbalans, om en klient först skickas till instans 1 när du loggar in, men sedan till instans # 2 när du hämtar en skyddad resurs till exempel , då kommer den andra instansen att hantera begäran som anonym, eftersom klientsessionen har lagrats lokalt i instans # 1 .

Det har hittats lösningar för att ta itu med detta problem (t.ex. genom att konfigurera sessionreplikering och / eller klibbig session ), men REST-arkitekturen föreslår ett annat tillvägagångssätt: gör bara inte din server statlig, gör den statslös . Enligt Fielding :

Varje begäran från klient till server måste innehålla all information som krävs för att förstå begäran och kan inte dra nytta av något lagrat sammanhang på servern. Sessionstillstånd hålls därför helt på klienten.

Med andra ord måste en begäran hanteras exakt på samma sätt, oavsett om den skickas till instans # 1 eller instans # 2 . Det är därför statslösa applikationer anses vara lättare att skala .

Hur?

En vanlig metod är en tokenbaserad autentisering , särskilt med de trendiga JSON Web Tokens . Observera att JWT fortfarande har några problem, särskilt när det gäller ogiltigförklaring och automatisk förlängning av giltighetstid (dvs. minnesfunktionen ).

Sidanmärkningar

Att använda kakor eller rubriker (eller något annat) har inget att göra med om servern är statlig eller statslös: det här är bara media som här används för att transportera tokens (sessionidentifierare för stateful-servrar, JWT, etc.), inget mer.

När ett RESTful API endast används av webbläsare kan ( HttpOnly och säkra ) kakor vara ganska praktiska eftersom webbläsare automatiskt kopplar dem till utgående förfrågningar. Det är värt att nämna att om du väljer cookies måste du vara medveten om CSRF (ett trevligt sätt att förhindra det är att låta klienterna generera och skicka samma unika hemliga värde i både en cookie och en anpassad HTTP-rubrik ).

Cacheable API med villkorade förfrågningar

Med den `Last-Modified` rubriken

Servern kan tillhandahålla ett Last-Modified datumhuvud till de svar som har resurser som är cachbara. Kunder ska sedan lagra detta datum tillsammans med resursen.

Nu, varje gång klienter begär API: et för att läsa resursen, kan de lägga till en begäran If-Modified-Since ändrats senast Last-Modified datum som de fick och lagrat till sina förfrågningar. Servern måste sedan jämföra begärans rubrik och resursens senast modifierade datum. Om de är lika returnerar servern en 304 (INTE ÄNDRAD) med en tom kropp: den begärande klienten bör använda den nuvarande cache-resursen den har.

När klienter begär att API ska uppdatera resursen (dvs. med ett osäkert verb), kan de lägga till en If-Unmodified-Since . Detta hjälper till att hantera loppförhållanden: om rubriken och det faktiskt senast modifierade datumet är olika, returnerar servern en 412 (PRECONDITION FAILED) . Klienten bör sedan läsa resursens nya tillstånd innan han försöker igen för att ändra resursen.

Med `ETag` rubriken

En ETag (entitetstagg) är en identifierare för ett specifikt tillstånd i en resurs. Det kan vara en MD5-hash för resursen för en stark validering , eller en domänspecifik identifierare för en svag validering .

I princip är processen densamma som med den Last-Modified rubriken: servern tillhandahåller en ETag rubrik till de svar som har resurser som är cachebara, och klienter bör sedan lagra denna identifierare tillsammans med resursen.

Sedan tillhandahåller klienter en rubrik- If-None-Match när de vill läsa resursen, innehållande den senaste ETag som de har tagit emot och lagrat. Servern kan nu returnera en 304 (INTE ÄNDRAD) om rubriken matchar den faktiska ETag för resursen.

Återigen kan klienter tillhandahålla en If-Match rubrik när de vill ändra resursen, och servern måste returnera en 412 (PRECONDITION FAILED) om den angivna ETag inte matchar den faktiska.

Ytterligare anmärkningar

ETag> datum

Om klienter lämnar både datum och ETag i sina förfrågningar måste datumet ignoreras. Från RFC 7232 ( här och här ):

En mottagare MÅSTE ignorera If-Modified-Since / If-Unmodified-Since om förfrågan innehåller ett If-None-Match / If-Match huvudfält; villkoret i If-None-Match / If-Match anses vara en mer exakt ersättning för villkoret i If-Modified-Since / If-Unmodified-Since , och de två kombineras endast för att samarbeta med äldre mellanhänder som kanske inte implementerar If-None-Match / If-Match .

Grunt ETags

Även om det är ganska uppenbart att de senaste modifierade datumen kvarstår tillsammans med resursens server-sida, finns flera tillvägagångssätt tillgängliga med ETag.

Ett vanligt tillvägagångssätt är att implementera grunt ET-taggar: servern bearbetar begäran som om inga villkorade rubriker har givits, men helt i slutet genererar den ETag för svaret som den håller på att returnera (t.ex. genom att haska det), och jämför det med den medföljande. Detta är relativt enkelt att implementera eftersom det bara behövs en HTTP-interceptor (och många implementeringar finns redan beroende på servern). Med det sagt är det värt att nämna att den här metoden sparar bandbredd men inte serverprestanda :

En djupare implementering av ETag-mekanismen kan potentiellt ge mycket större fördelar - som att betjäna vissa förfrågningar från cachen och inte behöva utföra beräkningen alls - men implementeringen skulle definitivt inte vara så enkel och inte så pluggbar som den grunda metoden beskrivs här.

Vanliga fallgropar

Varför ska jag inte sätta verb i en webbadress?

HTTP är inte RPC : det som gör HTTP betydligt annorlunda än RPC är att förfrågningarna riktas till resurser . Trots allt står URL för Uniform Resource Locator, och en URL är en URI : En Uniform Resource Idenfitier. Webbadressen riktar sig till resursen du vill ta itu med , HTTP-metoden anger vad du vill göra med den . HTTP-metoder är också kända som verb : verb i URL: er har ingen mening. Observera att HATEOAS-relationer inte borde innehålla verb, eftersom länkar också är inriktade på resurser.

Hur uppdaterar jag en resurs delvis?

När PUT förfrågningar ber kunderna skicka hela resursen med de uppdaterade värdena, kan PUT /users/123 inte användas för att helt enkelt uppdatera användarens e-post till exempel. Som förklarats av William Durand i Please. Lappa inte som en idiot. , finns flera REST-kompatibla lösningar tillgängliga:

Exponera resursens egenskaper och använd PUT metoden för att skicka ett uppdaterat värde, eftersom PUT specifikationen säger att partiella innehållsuppdateringar är möjliga genom att rikta in sig på en separat identifierad resurs med tillstånd som överlappar en del av den större resursen :

PUT https://example.com/api/v1.2/users/123/email
body:
  new.email@example.com

Använd en PATCH begäran som innehåller en uppsättning instruktioner som beskriver hur resursen måste modifieras (t.ex. efter JSON Patch ):

PATCH https://example.com/api/v1.2/users/123
body:
  [
    { "op": "replace", "path": "/email", "value": "new.email@example.com" }
  ]

Använd en PATCH begäran som innehåller en partiell representation av resursen, som föreslagits i Matt Chapmans kommentar :

PATCH https://example.com/api/v1.2/users/123
body:
  {
    "email": "new.email@example.com"
  }

Vad sägs om åtgärder som inte passar in i världen av CRUD-operationer?

Citera Vinay Sahni i bästa praxis för att utforma ett pragmatiskt RESTful API :

Det är här saker kan bli luddiga. Det finns ett antal tillvägagångssätt:
Omstrukturerar åtgärden så att den ser ut som ett resursfält. Detta fungerar om åtgärden inte tar parametrar. Till exempel kan en aktiveringsåtgärd mappas till ett booleskt activated fält och uppdateras via en PATCH till resursen.
Behandla det som en underresurs med RESTful principer. Till exempel låter GitHubs API dig stjärna med PUT /gists/:id/star och unstar med DELETE /gists/:id/star .
Ibland har du verkligen inget sätt att kartlägga handlingen till en förnuftig RESTful struktur. Till exempel är det inte riktigt meningsfullt att en sökning med flera resurser tillämpas på en specifik resurs slutpunkt. I det här fallet skulle /search vara mest meningsfull även om det inte är en resurs. Det här är OK - gör bara vad som är rätt ur API-konsumentens perspektiv och se till att det är dokumenterat tydligt för att undvika förvirring.

Vanliga metoder

API är dokumenterat. Verktyg finns tillgängliga för att hjälpa dig bygga din dokumentation, t.ex. Swagger eller Spring REST Docs .
API versioneras , antingen via rubriker eller via URL:

https://example.com/api/v1.2/blogs/123/articles
                        ^^^^

Resurser har flera namn :

https://example.com/api/v1.2/blogs/123/articles
                             ^^^^^     ^^^^^^^^

URL: er använder kebab-fall (orden är lägre och dash-separerade):

https://example.com/api/v1.2/quotation-requests
                             ^^^^^^^^^^^^^^^^^^

HATEOAS tillhandahåller en "själv" -länk till resurser och riktar sig mot sig själva:

{
  ...,
  _links: {
    ...,
    self: { href: "https://example.com/api/v1.2/blogs/123/articles/789" }
    ^^^^
  }
}

HATEOAS-relationer använder lägreCamelCase (ord läggs ned med små bokstäver, sedan aktiveras med undantag av det första, och mellanslag utelämnas), för att tillåta JavaScript-klienter att använda punktnotationen samtidigt som de respekterar JavaScript-namngivningskonventionerna när du öppnar länkarna:

{
  ...,
  _links: {
    ...,
    firstPage: { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=1&pageSize=25" }
    ^^^^^^^^^
  }
}

Blogghantering via ett RESTful HTTP API

Följande exempel använder HAL för att uttrycka HATEOAS, och använder sig av:

CURIE (Compact URI): används för att tillhandahålla länkar till API-dokumentation
URI-mallar : URI som innehåller parametrar som måste ersättas innan URI-lösningen löses

Skaffa blogg 123

Begäran

GET https://example.com/api/v1.2/blogs/123
headers:
  Accept: application/hal+json

Svar

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 123,
    "title": "The blog title",
    "description": "The blog description",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123" },
      "doc:articles": { "href": "https://example.com/api/v1.2/blogs/123/articles{?pageIndex,pageSize}", "templated": true }
    }
  }

Skapa en ny artikel i blogg 123

Begäran

POST https://example.com/api/v1.2/blogs/123/articles
headers:
  Content-Type: application/json
  Accept: application/hal+json
  X-Access-Token: XYZ
body:
  {
    "title": "The title 2",
    "content": "The content 2"
  }

Svar

status: 201 (CREATED)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2",
    "content": "The content 2",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

Få artikel 789 i blogg 123

Begäran

GET https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Accept: application/hal+json

Svar

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2",
    "content": "The content 2",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

Få fjärde sidan av 25 artiklar i blogg 123

Begäran

GET https://example.com/api/v1.2/blogs/123/articles?pageIndex=4&pageSize=25
headers:
  Accept: application/hal+json

Svar

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "pageIndex": 4,
    "pageSize": 25,
    "totalPages": 26,
    "totalArticles": 648,
    "_link": {
      "firstPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=1&pageSize=25" },
      "previousPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=3&pageSize=25" },
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=4&pageSize=25" },
      "nextPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=5&pageSize=25" },
      "lastPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=26&pageSize=25" }
    },
    "_embedded": [
      {
        ...
      }, {
        "id": 456,
        "title": "The title 1",
        "content": "The content 1",
        "_links": {
          "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
          "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/456" },
          "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
          "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/456/comments{?pageIndex,pageSize}", "templated": true }
        }
      }, {
        "id": 789,
        "title": "The title 2",
        "content": "The content 2",
        "_links": {
          "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
          "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
          "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
          "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
        }
      }, {
        ...
      }
    ]
  }

Uppdatera artikel 789 i blogg 123

Begäran

PUT https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Content-Type: application/json
  Accept: application/hal+json
  X-Access-Token: XYZ
body:
  {
    "id": 789,
    "title": "The title 2 updated",
    "content": "The content 2 updated"
  }

Svar

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2 updated",
    "content": "The content 2 updated",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

anteckningar

Identifieraren som används för att identifiera resursen som ska uppdateras är den i URL : en i kroppen (om någon) måste tyst ignoreras.
När en PUT förfrågan uppdaterar hela resursen, om inget content skulle ha skickats, borde det ha tagits bort från den fortsatta resursen.

Radera artikel 789 i blogg 123

Begäran

DELETE https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Accept: application/hal+json
  X-Access-Token: XYZ

Svar

status: 204 (NO CONTENT)
headers:
  Content-Type: application/hal+json
body:
  {
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" }
    }
  }

Kränker REST

<stock>
    <add>
        <item>
            <name>Milk</name>
            <quantity>2</quantity>
        </item>
    </add>
</stock>

Att lägga detta organ till en resurs som /stocks/123 bryter mot tanken bakom REST. Medan denna kropp put och den innehåller all nödvändig information, kommer den också tillsammans med ett metodsamtal att add någonstans när kroppen bearbetas. Efter REST skulle man lägga item till /stocks/123/items/ .

Modified text is an extract of the original Stack Overflow Documentation

Licensierat under CC BY-SA 3.0

Inte anslutet till Stack Overflow

Anmärkningar

REST Översikt

RESTA över HTTP

Richardson Mognadsmodell

HTTP-förfrågningar och svar

Vanliga HTTP-svarstatus

Framgång

Omdirigering

Klientfel

Serverfel

anteckningar

HATEOAS

Mediatyper

Statslös> statlig

Varför?

Hur?

Sidanmärkningar

Cacheable API med villkorade förfrågningar

Med den Last-Modified rubriken

Med ETag rubriken

Ytterligare anmärkningar

ETag> datum

Grunt ETags

Vanliga fallgropar

Varför ska jag inte sätta verb i en webbadress?

Hur uppdaterar jag en resurs delvis?

Vad sägs om åtgärder som inte passar in i världen av CRUD-operationer?

Vanliga metoder

Blogghantering via ett RESTful HTTP API

Skaffa blogg 123

Begäran

Svar

Skapa en ny artikel i blogg 123

Begäran

Svar

Få artikel 789 i blogg 123

Begäran

Svar

Få fjärde sidan av 25 artiklar i blogg 123

Begäran

Svar

Uppdatera artikel 789 i blogg 123

Begäran

Svar

anteckningar

Radera artikel 789 i blogg 123

Begäran

Svar

Kränker REST

Med den `Last-Modified` rubriken

Med `ETag` rubriken