REpresentational State Transfer (REST) · distinguished by MIME type. WWW on ehkä tunnetuin...

206

REpresentational State Transfer(REST)

207

ReST• Proposed by Roy Fielding

– In his PhD dissertation ”Architectural styles and the design of network-based software architectures”, University of California, Irvine, USA, 2000.

• ReST is an architectural style (originally for distributedhypermedia systems) that aims at retaininginteroperability among systems that may evolveindependently. In order to achieve this goal, ReSTdefines a set of interface constraints.

• Later, ReST has been proposed as an alternative view to loosely-coupled services in general.

ReST on arkkitehtuurityyli, joka tähtää yhteentoimivuuden säilyttämiseen sellaisissa hajautetuissa

(hypermedia)järjestelmissä, joissa eri osapuolet kehittyvät ja muuttuvat itsenäisesti toisistaan

riippumatta.

ReSTin ”isä” on Roy Fielding, joka esittelee tämän arkkitehtuurityylin väitöskirjassaan ”Architectural

styles and the design of network-based software architectures”, University of California, 2000. Katso

myös esim. ReST Wiki, jossa ReST on kuvattu kompaktisti ja pääpiirteittäin. Myöhemmin kiinnostus

ReSTiä kohtaan on kasvanut laajemminkin ja sitä pidetäänkin vaihtoehtoisena tapana toteuttaa löyhästi

sidottuja palvelupohjaisia järjestelmiä.

208

ReST – Representational StateTransfer

• Representation– Bytes that represent a resource

• A resource can be anything we are interested in and that can be identified(by a URI)

• One resource can have may representations

• State– A resource has a state at the server– A client application has a state

• Transfer– Client applications transfer states to the server in order to

update server's resource state– Client applications get states from the server to update its

own state

ReST tulee sanoista Representational State Trasfer. Näistä sanoista ensimmäinen (representational)

viittaa ReSTin avainkäsitteen – resurssin – esitysmuotoon. Resurssit puolestaan voivat olla mitä

tahansa kiinnostuksen kohteita (vrt. substantiivit) verkossa, joihin voidaan viitata yksikäsitteisellä

tavalla. ReSTissä tämä viittaustapa on URIt. Yhdellä resurssilla voi olla useita esitysmuotoja.

Tilan (state) käsite on myös oleellinen. Itse resurssilla on tila (palvelimella) ja myös

asiakassovelluksella on tila. ReST-kutsuilla käytännössä muutetaan resurssin ja asiakkaan tilaa:

asiakkaat voivat päivittää resurssin tilaa ja toisaalta asiakkaiden omaa tilaa voidaan päivittää resurssilta

haetun datan perusteella. Kaikki kutsut eivät kuitenkaan välttämättä muuta resurssin tilaa. Tällaisia

siinä mielessä turvallisia kutsuja ovat esim. tiedon haut.

209

ReST characteristics and constraints

• Application state and functionality are divided into resources– ReST is resource-oriented

• Every resource is uniquely addressable using a universal syntax for use in hypermedia links

• All resources share a uniform interface for the transfer of state between client and resource, which consists of standard way to address of resources and fixed set of operations– Resources are identified by URIs– Typical ReST applications use HTTP: standard methods (get,

post, put, delete) and standard respond codes

REST määrittelee joukon rajoitteita, joita noudattamalla yhteentoimivuus eri resurssien välillä

voitaisiin taata. Jokaisella resurssilla tulee ensinnäkin olla yksikäsitteinen osoite, joka annetaan

hypermedialinkkien käyttämän yleisen syntaksin avulla. Tämän avulla resurssit ovat tunnistettavissa ja

niihin voidaan viitata. REST-pohjaiset järjestelmät nojautuvat tyypillisesti (mutta eivät välttämättä)

HTTP:n käyttöön, jolloin resurssien yksikäsitteiset osoitteet annetaan URIen avulla.

Lisäksi ReSTin kaikilla resursseilla tulee olla samanlainen rajapinta. Tässä(kin) suhteessa ReST siis

poikkeaa Web-palvelukonseptista, jossa jokainen palvelu (tai palvelun tarjoaja) määrittelee oman

rajapintansa (esim. operaatiot, joita voidaan kutsua). ReSTissä taas operaatiojoukko on määrätty.

Tällöin myös niiden semantiikka on tunnettu. ReSTissä sanomina ovat resurssien tilojen muutokset tai

kyselyt. ReSTissä käytetään tyypillisesti XML:ää standardiformaattina datalle. Tästä johtuen ReSTin

voidaan ajatella keskittyvän datan siirtämiseen resurssien välillä, kun taas esimerkiksi Web-palvelut

kuljettavat XML-formaattiin muunnettuja operaatiokutsuja SOA-kirjekuoressa esimerkiksi HTTP-

yhteyden yli. Näin ollen voidaan edelleen myös sanoa, että ReSTissä data on kommunikaatiossa

avainasemassa operaatioiden sijaan.

210

ReST characteristics and constraints

• To obtain a uniform interface, ReSTdefines four interface constraints– Identification of resources– Manipulation of resources through

representations– Self-descriptive messages– Hypermedia as the engine of application

state

Viimeinen rajoite (hypermedia as the engine of application state) tarkoittaa käytännössä sitä, että

palvelimelta saadut vastaukset sisältävät URIt kaikkeen mitä voidaan seuraavaksi tehdä. Tämän

ymmärtämiseksi kannattaa ajatella Webiä ja erityisesti HTML-dokumentteja. Tämän rajoitteen vuoksi

sovellusta voidaan ajatella tilakoneena, jossa jokainen sivu on tila ja linkit edustavat mahdollisia

tilasiirtymiä kyseisellä hetkellä aktiivisesta tilasta.

211

ReST and HTTP methods

• From the the point of view of ReST,– HTTP is an application protocol that can be used for

transferring representations– The key points are:

• Relying on standard, • visible semantics of its fixed set of operations.

• Most important HTTP methods are PUT, GET, POSTand DELETE. – c.f. CREATE, READ, UPDATE, DELETE (CRUD) operations

associated with database technologies.– c.f cut and paste:

• PUT is analogous to CREATE or PASTE OVER, • GET to READ or COPY, • POST to UPDATE or PASTE AFTER, • and DELETE to DELETE or CUT.

Kuten aiemmin todettiin, ReSTissä tavoitteena on määrätyt ja universaalit resurssien/palveluiden

rajapinnat ja niiden tarjoamat operaatiot. HTTP:n käyttö ReSTin näkökulmasta tarjoaakin vastaukset

tärkeisiin tavoitteisiin: standardiin nojautuminen ja määrätty operaatiojoukko. Nämä puolestaan

implikoivat sen, että operaatioiden semantiikka on tunnettu. Nämä operaatiot vastaavat

tietokantateknologioista tuttuja nk. CRUD-operaatioita: luo/lisää (create), lue (read), päivitä (update) ja

tuhoa (delete). HTTP tarjoaakin operaatiot put, get, post ja delete tätä varten. Toisenlaisena analogiana

tälle määrätylle operaatiojoukolle ovat tutut ”leikkaa ja liimaa” operaatiot. Tällöin HTTP:n put-

operaatio vastaa operaatiota ”luo” (create) tai ”kopioi päälle” (paste over), get-operaatio vastaa

operaatiota ”lue” (read) tai ”kopioi” (copy), post-operaatio vastaa operaatioita ”päivitä” (update) tai

”kopioi loppuun” (paste after) ja delete-operaatio vastaa ”tuhoa” (delete) tai ”leikkaa” (cut) –

operaatiota.

212

ReST and HTTP methods• GET

– Retrieve a resource representation– Safe, since there are no side effects– Does not change the state of the resource– Idempotent: idem (same) + potent/potents (power), i.e. ”one gets it as

well as ten”

• DELETE– Delete resource at this URI, or more precisely, remove a resource by

rewriting its state with NULL– Unsafe & idempotent

• PUT– Rewrite or create a complete resource at this URI– Needs a body, i.e. – Unsafe & idempotent

• POST– Create something subordinate to this resource– Needs a body– Unsafe & not idempotent

Tällä ja seuraavalla kalvolla on käsitelty ReSTiä ja HTTP-operaatioita hieman tarkemmin. Jokaisen

operaation kohdalla on myös mainita sen (a) turvallisuudesta (safe/unsafe) ja (b) ”toistojen

samankaltaisuudesta” (idempotent/not idempotent). Näistä ensimmäinen viittaa siihen, muuttaako

operaatio resurssin tilaa. Jälkimmäinen (idempotent) on matematiikastakin tuttu termi (idempotent: a

mathematical quantity which when applied to itself under a given binary operation (as multiplication)

equals itself (Marriam-Webster)), joka kuitenkin tässä sen yleisemmän tulkinnan mukaan kuvaa sitä,

onko ko. operaatiokutsu samalla tavalla mahdollinen yhdelle kuin esimerkiksi kymmenelle muullekin.

213

ReST constraints• A protocol that is:

– Client/Server– Stateless:

• Means that the protocol should be stateless• No implicit state can be hidden between consecutive interactions

– All information needed is trasported with messages

– Cacheable– Layered

• allow intermediaries -- proxies, gateways, and firewalls -- to beintroduced at various points in the communication without changing the interfaces between components

• Code-on-demand– An optional constraint that allows extension of client

functionality (e.g. applets or scripts)

ReSTissä on myös useita protokollaa koskevia rajoitteita. Ensimmäinen tällainen rajoite Client/Server –

mallin käyttö, koska se (ainakin periaatteessa) yksinkertaistaa toteutusta, vähentää kutsujen

semantiikan kompleksisuutta, parantaa tehokkuutta ja lisää skaalautuvuutta. Toisena vaatimuksena on

tilattomuus (stateless). Tämä saattaa kuulostaa oudolta, koska tila (state) on osa itse akronyymia

(ReST). Tämä rajoite tarkoittaa kuitenkin sitä, protokolla on tilaton. Esim. minkäänlaista implisiittistä

tilaa ole ”piilotettu” peräkkäisten interaktioiden välille. Toisin sanoen, kaikki tarvittava informaatio

kuljetetaan viesteissä. Kolmantena vaatimuksena on mahdollisuus välimuistin käyttöön (cacheable).

Viimeisenä vaatimuksena on se, että protokolla koostuu kerroksista (layered). Tällöin palvelimen ja

asiakkaan välille voidaan asettaa esim. palomuureja, proxyja/välityspalvelimia muuttamatta rajapintoja

palvelimen ja asiakkaan välillä.

Tämän asti mainittujen rajoitteiden lisäksi ReSTiin kuuluu myös muita rajoitteita, joita kaikkia ei tässä

käydä läpi. Yhtenä jäljellä olevista rajoitteista mainittakoon kuitenkin optionaalinen rajoite, joka sallii

koodin (kuten appletit tai skriptit) käytön asiakkaan toiminnallisuuden laajentamiseksi ja

parantamiseksi.

214

WWW – and example of ReSTfuldesign

• The Web consists of HTTP, content types (e.g. HTML), and other internet technologies, such as DNS (Domain Name System)

• HTML can include javascript and applets to support “code-on-demand” principle

• HTTP has a uniform interface for accessing resources, which consists of URIs, methods, status codes, headers, and content distinguished by MIME type.

WWW on ehkä tunnetuin esimerkki ReST-periaatteiden mukaista arkkitehtuurityyliä noudattavasta

”järjestelmästä”. Ensinnäkin se koostuu HTTP:stä, sisältötyypistä (esim. HTML) sekä muista Internet-

teknologioista kuten DNS. HTML-dokumentti voi puolestaan sisältää koodia (esim. javascript-koodia

tai appletteja) ja näin ollen tukee ”code-on-demand” –periaatetta. Lisäksi HTTP:llä on yleinen ja

kaikille sama rajapinta resurssien osoittamiseen ja eri resurssien yksikäsitteiset osoitteet annetaan URI-

osoitteina.

215

ReST challenges

• Security– Rely on HTTP authentication framework (…only)– No standard for message-level security, c.f. Web

services– WS-Security might have some reusable solutions

• General and comprehensive service descriptionstandard (c.f. WSDL)…is there already: WADL

• Service compositions, choreographies/orchestrations– Would be, I believe, as relevant as in case of Web

services

ReSTissä on etujensa lisäksi myös puutteita. Yksi oleellisimmista on viestinvälityksen turvaaminen.

Tässä Web-palvelukonsepti on huomattavasti pidemmällä. Joitain WS-Securityn ratkaisuja on harkittu

hyödynnettäväksi myös ReST-puolella.

Lisäksi WSDL:ää vastaavaa palveluiden kuvauskieltä on odotettu jo jonkin aikaa. WADL pyrkii

vastaamaan tähän haasteeseen. Sen suosio onkin lisääntynyt nopeasti. Se on osittain myös vastine Web-

palvelukonseptin koreografia- ja orkestraatiokielille tarjoamalla tuke palveluiden yhdistämiselle.

WADL-kieltä käsitellään seuraavaksi.

216

Some acid tests for ReSTfulness(by Markku Laitkorpi)

• Can you bookmark this application state, email the link to yourself, and continue tomorrow?

• Can you just simply retry after a network fault?• Can you blindly continue using this service after I have

replaced and rebooted the server machine at any time• Can you expect to do this same thing over there, too?• Can you see what is happening to this resource?• Can you follow your nose without sticking it too deep?• Can you traverse from one thing to another?• Are your URIs cool and still refer to the same thing after next

upgrade? After 10 years?

ReSTiä – kuten niin monta muutakin teknologiaa, arkkitehtuurityyliä jne. – käytetään myös paljon

väärin. Tämä näkyy esimerkiksi siinä, että dataorientoitunutta ajattelutapaa ei olla oikein sisäistetty. Se

onkin usein hankalaa, varsinkin operaatio-orientoituneeseen ajattelutapaan tottuneille. Lisäksi ReSTin

rajoitteita ei aina ymmärretä oikein.

Tällä kalvolla on lueteltu Markku Laitkorven esittämiä ”happotestejä”, jotka ovat hyödyllisiä

”ReSTimäisyyden” toteamiseksi. Hän esitteli nämä happotestit syksyn 2008 kurssitoteutuksessa

vierailuluennollaan.

217

Examples of good ReST APIs

• See e.g.– Google Data API

• http://code.google.com/apis/gdata/overview.html

– Amazon S3 (and S4)• http://aws.amazon.com/s3/

Hyviä ReST-esimerkkejä löytyy toki muitakin. Kannattaa esimerkiksi tutustua Atom Publishing

Protocol (a.k.a. APP a.k.a. AtomPub) –esimerkkiin. Se on yksinkertainen HTTP-pohjainen protokolla

Web-resurssien luomista ja päivittämistä varten. Se kehitettiin alun alkaen vaihtoehdoksi RSS:lle.

Aiheeseen liittyen löytyy paljon esim. blogeja. Myös esimerkiksi Numbler on tutustumisen arvoinen.

218

Literature• Roy Fielding's 2007 Apachecon talk

– http://roy.gbiv.com/talks/200711_REST_ApacheCon.pdf

• Roy Fielding's PhD dissertation, “Architectural Styles and the Design of Network-Based Software Architectures”, 2000– http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

• Rohit Khare’s PhD dissertation, ”Extending the ReSTArchitectural Style for Decentralized Systems”, ICSE conference, 2004

• Leonard Richardson & Sam Ruby, RESTful Web Services,O'Reilly

• REST Wiki (http://rest.blueoxen.net) • rest-discuss on Yahoo!Groups

(http://tech.groups.yahoo.com/group/rest-discuss)

219

Web Application Description Language (WADL)

• An XML-based language

• Assumes HTTP

• Uses hyperlinks for linking resources

• Development both language and platform neutral

• Aligned with REST terminology

Tämä osio perustuu pääosin WADL spesifikaatioon (Marc J. Hadley, Sun Microsystems)

WADL on XML-pohjainen kieli verkkosovellusten kuvaamiseksi. Verkkosovellukset ovat puolestaan

WADL-spesifikaation mukaan sovelluksia, jotka

Pohjautuvat Web-arkkitehtuuriin ja –infrastruktuuriin,

Ovat riippumattomia ohjelmointikielestä ja –alustasta,

Tukevat sovellusten (uudelleen)käyttöä laajemmin kuin vain selaimen välityksellä,

Mahdollistavat yhdistämisen muiden Web- ja desktop-sovellusten kanssa ja

Edellyttää sisällön ja ennen kaikkea esitysmuodon (representations) semantiikan selkeyttä.

WADLin terminologia on linjassa ReST-terminologian kanssa. Osittain senkin vuoksi se onkin

nopeasti kasvattanut suosiotaan ReST-palveluiden kuvauskielenä.

220

Useful in a machine processable format of Web applications (from WADL spec.)

• Set of resources: Analogous to a site map showing the resources on offer.

• Relationships between resources: Describing the links between resources, both referential and causal.

• Methods that can be applied to each resource: The HTTP methods that can be applied to each resource, the expected inputs and outputs and their supported formats.

• Resource representation formats: The supported MIME types and data schemas in use

WADL-spesifikaatio esittelee muutamia Web-sovelluksien kuvauskielelle tärkeitä ominaisuuksia,

jonka on myös huomioitu WADL-kielessä. Nämä neljä omaisuutta kuvaavatkin WADLin

perusominaisuudet hyvin:

Resurssijoukko: kuten sivukartta, kuvaa käytettävissä/kutsuttavissa olevat resurssit

Resurssien suhteet: kuvaa linkkien väliset suhteet (referenssit, järjestykseen liittyvät)

Operaatiot, joilla resursseja voidaan kutsua: tuetut HTTP-operaatiot, niiden input/output

sekä niiden tuetut formaatit

Resurssin kuvaustavat (formaatit): Tuetut MIME-tyypit ja skeemat. Skeemat voidaan antaa

XML Scheman tai RelaxNG:n avulla.

221

Structure of WADL document

<application><doc/>*<grammars>

<doc/>*<include />*

</grammars>?<resources base='anyURI'>?

<doc/>*<resource id=‘ID’ type=‘resource_type_list’ queryType=‘string’ path=‘string'>+

<doc/>*<param/>*( <method/> | <resource/> )

</resource></resources>(<resource_type/> | <method/> | <representation/> | <param/>)*

</application>

WADL-dokumentin rakenne on melko yksinkertainen. Seuraavaksi katsotaan tarkemmin method-,

representation-, fault ja jresource_type –rakenteita.

Esimerkki (WADL Spec.): The following listing shows an example of a WADL description for the

Yahoo News Search application.

<?xml version="1.0"?>

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd"

xmlns:tns="urn:yahoo:yn"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:yn="urn:yahoo:yn"

xmlns:ya="urn:yahoo:api"

xmlns="http://wadl.dev.java.net/2009/02">

<grammars>

<include href="NewsSearchResponse.xsd"/>

<include href="Error.xsd"/>

</grammars>

222

method element

<method name=‘Method‘? id='ID'? href='anyURI'?><doc/>*<request>?

<param>*<representation/>*

</request><response>?

( <representation/> | <fault/> )*</response>

</method>

Method: union of HTTPMethods (GET,POST,PUT,HEAD,DELETE)

…Esimerkki (WADL Spec.) jatkuu:

<resources base="http://api.search.yahoo.com/NewsSearchService/V1/">

<resource path="newsSearch">

<method name="GET" id="search">

<request>

<param name="appid" type="xsd:string“ style="query" required="true"/>

<param name="query" type="xsd:string“ style="query" required="true"/>

<param name="type" style="query" default="all">

<option value="all"/>

<option value="any"/>

<option value="phrase"/>

</param>

<param name="results" style="query" type="xsd:int" default="10"/>

<param name="start" style="query" type="xsd:int" default="1"/>

<param name="sort" style="query" default="rank">

<option value="rank"/>

<option value="date"/>

</param>

223

param element

<param name='NMTOKEN'style='query|matrix|template|header‘href=’anyURI’?id=’ID’?type=‘string‘?default='string‘?path='string‘?required='boolean‘?repeating='boolean‘?fixed='string‘?>

<doc/>*<option/>*<link resource_type='anyURI‘? rel=‘token‘? rev=‘token‘?>

<doc/>*</link>?

</param>

224

resource_type and representationelements

<resource_type id='ID'? ><doc/>*<param/>*(<method/> | <resource/>)*

</resource_type>

<representation id='ID‘? element=‘QName’? mediaType=‘string’? href=‘anyURI’? profile=‘uriList’?>

<doc/>*<param/>*

</resource_type>

225

Tool support and information sources

• Sun Web Developer Pack – RESTful Web Services API (EA)– Automatic generation of WADL files– Still at early phase, but many improvements are planned– Prebuilt binaries for wadl2java– Source code for Yahoo News Search sample– http://developers.sun.com/web/swdp/, https://wadl.dev.java.net/

• Google REST tools– Google REST Compile

• c.f wadl2java– Google REST Describe

• Support for building WADL descriptions for services– Sample requests and responses are analyzed, heuristics are used to

extract descriptive information– The user can later revise the generated description by manually

add/modify metadata

• Marc J. Hadley, Web Application Description Language (WADL) spec., Sun Microsystems, November 2006

Työkalutukea WADLille on jo olemassa. Yksi esimerkki on Sun Web Developer Pack. Lisätietoa

löytyy myös GlassFish-projektin sivuilta. Myös mm. Google ja NetBeans tarjoavat tutustumisen

arvoisia työkaluja.

WADLiin kannattaa – kuten muihinkin standardeihin – tutustua myös esimerkkien avulla. Myös esim.

Joe Gregorion blogi-kirjoitukset ovat mielenkiintoista luettavaa. Hieman kriittisemmän näkökulman

hän esittää esimerkiksi haastattelussa ”Do we need WADL?” (http://bitworking.org/news/193/Do-we-

need-WADL). Muita aktiivisia ja asiantuntevia ReST/WADL –aiheista kirjoittavia ovat mm. Mark

Baker, Benjamin Carlyle, Duncan Cragg, Mark Nottingham, Sam Ruby ja Stefan Tilkov.

REpresentational State Transfer (REST) · distinguished by MIME type. WWW on ehkä tunnetuin...

Documents

Transcript of REpresentational State Transfer (REST) · distinguished by MIME type. WWW on ehkä tunnetuin...