REpresentational State Transfer (REST)

REpresentational State Transfer (REST) 206

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 distributed hypermedia systems) that aims at retaining interoperability among systems that may evolve independently. In order to achieve this goal, ReST defines a set of interface constraints. Later, ReST has been proposed as an alternative view to loosely-coupled services in general. 207 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ä.

ReST Representational State Transfer 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 208 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.

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 209 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 HTTPyhteyden yli. Näin ollen voidaan edelleen myös sanoa, että ReSTissä data on kommunikaatiossa avainasemassa operaatioiden sijaan.

ReST characteristics and constraints To obtain a uniform interface, ReST defines four interface constraints Identification of resources Manipulation of resources through representations Self-descriptive messages Hypermedia as the engine of application state 210 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.

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, POST and 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. 211 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 putoperaatio 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.

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 212 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.

ReST constraints A protocol that is: Client/Server Stateless: Means that the protocol shouldbestateless 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 be introduced 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) 213 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.

WWW and example of ReSTful design 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. 214 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 Internetteknologioista 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 URIosoitteina.

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 description standard (c.f. WSDL) is there already: WADL Service compositions, choreographies/orchestrations Would be, I believe, as relevant as in case of Web services 215 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 Webpalvelukonseptin koreografia- ja orkestraatiokielille tarjoamalla tuke palveluiden yhdistämiselle. WADL-kieltä käsitellään seuraavaksi.

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? 216 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.

Examples of good ReST APIs See e.g. Google Data API http://code.google.com/apis/gdata/overview.ht ml Amazon S3 (and S4) http://aws.amazon.com/s3/ 217 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.

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 ReST Architectural 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) 218

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 219 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ä.

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 220 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.

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> 221 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>

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) 222 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>

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> 223

resource_type and representation elements <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> 224

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 225 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-weneed-wadl). Muita aktiivisia ja asiantuntevia ReST/WADL aiheista kirjoittavia ovat mm. Mark Baker, Benjamin Carlyle, Duncan Cragg, Mark Nottingham, Sam Ruby ja Stefan Tilkov.