representational state transfer (rest) · distinguished by mime type. www on ehkä tunnetuin...
TRANSCRIPT
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>
<param name="language" style="query" type="xsd:string"/>
</request>
<response status="200">
<representation mediaType="application/xml“ element="yn:ResultSet"/>
</response>
<response status="400">
<representation mediaType="application/xml“ element="ya:Error"/>
</response>
</method>
</resource>
</resources>
</application>
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.