Free Press

REST API:n avulla voit kehittää minkä tahansa verkkosovelluksen, jossa on kaikki mahdolliset CRUD-operaatiot (create, retrieve, update, delete). REST-ohjeet suosittelevat tietyn HTTP-menetelmän käyttämistä tietyntyyppisiin palvelimelle tehtyihin kutsuihin (vaikka teknisesti on mahdollista rikkoa tätä ohjetta, sitä ei kuitenkaan suositella).

Käytä alla olevia tietoja löytääksesi sopivan HTTP-menetelmän API:n suorittamaan toimintoon.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Käytä GET-pyyntöjä vain resurssin esityksen/tiedon hakemiseen – etkä muokkaamiseen millään tavalla. Koska GET-pyynnöt eivät muuta resurssin tilaa, näitä sanotaan turvallisiksi menetelmiksi. Lisäksi GET-API:iden tulisi olla idempotentteja, mikä tarkoittaa, että useiden samanlaisten pyyntöjen tekemisen on tuotettava sama tulos joka kerta, kunnes jokin toinen API (POST tai PUT) on muuttanut resurssin tilaa palvelimella.

Jos Request-URI viittaa dataa tuottavaan prosessiin, vastauksessa on palautettava tuotettu data entiteettinä eikä prosessin lähdetekstiä, ellei tämä teksti satu olemaan prosessin tuotos.

Minkä tahansa HTTP GET API:n osalta, jos resurssi löytyy palvelimelta, sen on palautettava HTTP-vastauskoodi 200 (OK) – yhdessä vastauksen rungon kanssa, joka on yleensä joko XML- tai JSON-sisältöä (johtuen niiden alustariippumattomasta luonteesta).

Jos resurssia EI löydy palvelimelta, sen on palautettava HTTP-vastauskoodi 404 (NOT FOUND). Vastaavasti jos todetaan, että itse GET-pyyntöä ei ole muodostettu oikein, palvelin palauttaa HTTP-vastauskoodin 400 (BAD REQUEST).

Esimerkki pyynnön URI:t

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/address

HTTP POST

Käyttäkää POST-API:itä luodaksenne uusia alisteisia resursseja, esim, tiedosto on alisteinen sen sisältävälle hakemistolle tai rivi on alisteinen tietokantataululle. Puhuttaessa tiukasti RESTistä, POST-menetelmiä käytetään uuden resurssin luomiseen resurssikokoelmaan.

Jos resurssi on luotu alkuperäisellä palvelimella, vastauksen PITÄISI olla HTTP-vastauskoodilla 201 (Created) ja sen PITÄISI sisältää pyynnön tilaa kuvaavan ja uuteen resurssiin viittaavan olion sekä Location-otsikon.

Monesti POST-menetelmällä suoritettu toiminto ei välttämättä johda URI:n avulla tunnistettavaan resurssiin. Tällöin joko HTTP-vastauskoodi 200 (OK) tai 204 (No Content) on sopiva vastaustila.

Tälle metodille annetut vastaukset eivät ole välimuistissa, ellei vastaus sisällä asianmukaisia Cache-Control- tai Expires-otsakekenttiä.

Huomaa, että POST-menetelmä ei ole turvallinen eikä idempotenttinen, ja kahden identtisen POST-pyynnön esittäminen johtaa kahteen erilaiseen resurssiin, jotka sisältävät samoja tietoja (resurssien tunnuksia lukuun ottamatta).

Esimerkki pyyntöjen URI:t

• HTTP POST http://www.appdomain.com/users
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

Käyttäkää PUT-API:itä ensisijaisesti olemassa olevan resurssin päivittämiseen (jos resurssia ei ole olemassa, API voi päättää, luodaanko uusi resurssi vai eikö luoda). Jos PUT API on luonut uuden resurssin, alkuperäisen palvelimen PITÄÄ ilmoittaa siitä käyttäjäagentille HTTP-vastauskoodilla 201 (Created)-vastauksella, ja jos olemassa olevaa resurssia muutetaan, joko 200 (OK) tai 204 (No Content) vastauskoodit PITÄÄ lähettää ilmaisemaan pyynnön onnistunut loppuunsaattaminen.

Jos pyyntö kulkee välimuistin kautta ja Request-URI tunnistaa yhden tai useamman tällä hetkellä välimuistissa olevan entiteetin, näitä merkintöjä PITÄÄ käsitellä vanhentuneina. Tämän menetelmän vastaukset eivät ole välimuistissa.

Esimerkki pyyntö-URI:t

• HTTP PUT http://www.appdomain.com/users/123
• HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE

Nimensä mukaisesti DELETE API:ia käytetään resurssien poistamiseen (jotka on yksilöity Request-URI:lla).

DELETE-pyyntöjen onnistuneen vastauksen PITÄÄ olla HTTP-vastaus code 200 (OK), jos vastaus sisältää tilaa kuvaavan entiteetin, 202 (Accepted), jos toiminto on asetettu jonoon, tai 204 (No Content), jos toiminto on suoritettu, mutta vastaus ei sisällä entiteettiä.

DELETE-operaatiot ovat idempotentteja. Jos DELETE-resurssi poistetaan resurssikokoelmasta, se poistetaan resurssikokoelmasta. Toistuva DELETE-API:n kutsuminen kyseiselle resurssille ei muuta lopputulosta – sen sijaan DELETE:n kutsuminen resurssille toisen kerran palauttaa 404 (NOT FOUND) -ilmoituksen, koska resurssi on jo poistettu. Jotkut saattavat väittää, että tämä tekee DELETE-menetelmästä epäidempotentin. Se on keskustelukysymys ja henkilökohtainen mielipide.

Jos pyyntö kulkee välimuistin läpi ja Request-URI tunnistaa yhden tai useamman tällä hetkellä välimuistissa olevan entiteetin, näitä merkintöjä PITÄÄ käsitellä vanhentuneina. Tämän menetelmän vastaukset eivät ole välimuistissa.

Esimerkki pyyntö-URI:t

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

HTTP PATCH -pyyntöjen tarkoituksena on tehdä osittainen päivitys resurssille. Jos näet, että PUT-pyynnöt muuttavat myös resurssikokonaisuutta, niin selvyyden vuoksi – PATCH-menetelmä on oikea valinta olemassa olevan resurssin osittaiseen päivittämiseen, ja PUT-menetelmää tulisi käyttää vain, jos korvaat resurssin kokonaisuudessaan.

Huomaa, että on olemassa joitain haasteita, jos päätät käyttää PATCH-rajapintoja sovelluksessasi:

• Tuki PATCH:lle ei ole yleispätevä selaimissa, palvelimissa ja web-sovellusympäristöissä. IE8:lta, PHP:ltä, Tomcatilta, Djangolta ja monilta muilta ohjelmistoilta puuttuu tuki tai se on rikki.
• Patch-pyynnön hyötykuorma ei ole suoraviivainen kuten PUT-pyynnön. esim.

  HTTP GET /users/1

  tuottaa alla olevan vastauksen:

  {id: 1, username: 'admin', email: ''}

  Esimerkki patch-pyynnöstä sähköpostin päivittämiseksi on seuraavanlainen:

  HTTP PATCH /users/1

  ” }
  ]

Mahdollisia operaatioita voi olla HTTP-spesifikaation mukaan seuraavat.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

PATCH-menetelmä ei korvaa POST- tai PUT-menetelmiä. Se soveltaa deltaa (diff) sen sijaan, että se korvaisi koko resurssin.

Yhteenveto RESTful API:n HTTP-menetelmistä

Alla olevaan taulukkoon on koottu yhteenveto edellä käsiteltyjen HTTP-menetelmien käytöstä.

Luettelo

Turvalliset menetelmät

HTTP-spesifikaation mukaan GET- ja HEAD-menetelmiä tulisi käyttää vain resurssin esitysten hakemiseen – eikä niillä päivitetä/poisteta resurssia palvelimella. Molempien menetelmien sanotaan olevan ”turvallisia”.

Tämän ansiosta käyttäjäagentit voivat esittää muita menetelmiä, kuten POST, PUT ja DELETE, yksilöllisellä tavalla niin, että käyttäjälle ilmoitetaan, että pyydetään mahdollisesti vaarallista toimintaa – ja ne voivat päivittää/poistaa resurssin palvelimella, joten niitä tulisi käyttää varoen.

Idempotenttiset metodit

Termiä idempotentti käytetään kattavammin kuvaamaan operaatiota, joka tuottaa samat tulokset, jos se suoritetaan kerran tai useita kertoja. Idempotenttius on kätevä ominaisuus monissa tilanteissa, sillä se tarkoittaa, että operaatio voidaan toistaa tai yrittää uudelleen niin usein kuin on tarpeen aiheuttamatta tahattomia vaikutuksia. Ei-idempotenttien operaatioiden kohdalla algoritmi saattaa joutua seuraamaan, onko operaatio jo suoritettu vai ei.

HTP-määrittelyssä metodit GET, HEAD, PUT ja DELETE on julistettu idempotentteiksi metodeiksi. Muilla metodeilla OPTIONS ja TRACE EI SAA olla sivuvaikutuksia, joten molemmat ovat myös luonnostaan idempotentteja.