REST - Representational State Transfer

Sisällysluettelo

1 REST

Lisää aiheesta:

2 Periaatteet

Vaikka REST yleensä liitetäänkin WWW:hen ja HTTP-protokollaan, onhan se WWW:n arkkitehtuuri, ei REST-ajattelutapana ole sidottu HTTP-protokollaan. REST-arkkitehtuurin voi rakentaa mille tahansa alustalle, kun pitää mielessä seuraavat periaatteet.

2.1 Client–server

Asiointi tapahtuu asiakas-palvelin -mallin mukaisesti, eli järjestelmässä aina asiakasroolissa oleva komponentti esittää vaateen (request) palvelinroolissa toimivalle komponentille. Palvelin vastaa vaateeseen palauttamalla vasteen (response). Huomaa, että komponentin roolit voivat muuttua ajon aikana, ja sama komponentti toimia sekä asiakkaana, että palvelimena. Palvelimen tehtävänä on edustaa jotain resurssia (julkaista resurssi), jota asiakkaat haluavat käyttää. Käyttö tapahtuu yhtenäisen rajapinnan välityksellä.

2.2 Stateless

REST-järjestelmät ovat tilattomia. Asiakkaalla on toki oma tilansa, kuten tietysti palvelimella, mutta tila ei liiku asiakkaan ja palvelimen välillä. Toisin sanoen palvelimen toiminta ei saa olla mitenkään riippuvainen asiakkaan tilasta. Jos asiakkaan tilatieto on jotenkin palvelimelle tärkeää, asiakas välittää sen palvelimelle lähettämässään vaateessa.

2.3 Cacheable

2.4 Layered system

2.5 Code on demand (optional)

2.6 Uniform Interface

3 REST llä

3.1 URL

  • nimeää yhden resurssin
  • resurssilla voi olla monta nimeä

3.2 GET

  • hakee, laskee
  • idempotentti
  • turvallinen

3.2.1 HEAD

  • GET ilman hyötykuormaa

3.3 PUT

  • muokkaa
  • idempotentti

3.4 POST

  • lisää jonkin alle
  • luo jonkin alle
    • tulee palauttaa luodun resurssin osoite
  • ei idempotentti
  • ei turvallinen

3.5 DELETE

  • poistaa resurssin
  • idempotentti
  • ei turvallinen

3.6 OPTIONS

  • mitkä HTTP-metodit tarjolla resurssille

3.7 LINK

3.8 UNLINK

3.9 PATCH

  • resurssin hienojakoisempi muokkaus (PUT muokkaa kerralla koko resurssia)
  • tulossa

4 Hypermedia (HATEOAS)

  • resurssit linkittyvät toisiinsa
  • myös linkin tarkoitus kerrottava
    • vrt jälleen konseptikartat :)

5 Sisällön muodon neuvottelu

Muista linkit ja hypermedia!

5.1 Internet Media Types (aka MIME-types)

5.2 XML

5.3 JSON

5.3.1 application/____+json

5.4 Kaikki muu

6 Tietoturva

  • Authentication
  • HTTPS

7 Tärkeimmät status-koodit

200 (“OK”) Everything’s fine. The document in the entity-body, if any, is a representation of some resource.

400 (“Bad Request”) There’s a problem on the client side. The document in the entity-body, if any, is an error message. Hopefully the client can understand the error message and use it to fix the problem.

500 (“Internal Server Error”) There’s a problem on the server side. The document in the entity-body, if any, is an error message. The error message probably won’t do much good, since the client can’t fix a server problem. There are four more error codes that are especially common in web services:

301 (“Moved Permanently”) Sent when the client triggers some action that causes the URI of a resource to change. Also sent if a client requests the old URI.

404 (“Not Found”) and 410 (“Gone”) Sent when the client requests a URI that doesn’t map to any resource. 404 is used when the server has no clue what the client is asking for.

410 is used when the server knows there used to be a resource there, but there isn’t anymore.

409 (“Conflict”) Sent when the client tries to perform an operation that would leave one or more resources in an inconsistent state.

8 Toteutuksia

8.1 Mikä tahansa HTTP-palvelinkehys… melkein mikä tahansa

8.2 JAX-RS

8.3 Liberator

9 REST-palvelun toteutus

  1. Figure out the data set
  2. Split the data set into resources

For each kind of resource:

  1. Name the resources with URIs
  2. Expose a subset of the uniform interface
  3. Design the representation(s) accepted from the client
  4. Design the representation(s) served to the client
  5. Integrate this resource into existing resources, using hypermedia links and forms
  6. Consider the typical course of events: what’s supposed to happen?
  7. Consider error conditions: what might go wrong?

Validate