Programmable Web I

1. Programmable Web I • ReSTful Web Services • Using ReST to support a generic API • Atom • Modeling Resource Oriented APIs • Web Application Description Language

2. ReSTful Web Services • We looked at SOAP based Web Services • Service Oriented • Services DO things • The operations are defined in the WSDL file • A single endpoint (service endpoint) may do many things • Data types used by the service are exposed in the WSDL and described in a machine processable format (usually XML Schema) • SOAP envelope is tunneled via the HTTP POST method • So what is a ReSTful Web Service? • Resource Oriented • A resource is something with at least one URI • Follows the grain of the Web • Uses URIs, HTTP methods, MIME types

3. ReSTful Web Services • What data the service operates on is defined by the URI • What the service going to do with the data is defined by the HTTP methods • SOAP based services combine these two things into a service Operation. • A single service may have many operations that do many different things • But they use only one HTTP method: POST irrespective of the semantics of the service operation. • ReSTful Web Services have only a handlful of operations • They ALL share the same operations • They use the semantics of the HTTP method: DELETE means DELETE

4. ReSTful Web Services • Addressability • Using URIs, every bit of interesting data on a server becomes addressable, each with its own address • This means I can share the addresses just by sharing the URI • In a SOAP based service, you have to create a client, invoke the correct operation and give it the correct parameters • Connectedness • Hypermedia – resource representations contain URIs of related resource. • I can have a service that links to other services • In SOAP based services you have one endpoint – the service endpoint. WSDL is not hypermedia • Hard to explicitly link with other services

5. Statelessness • Remember statelessness in ReST • Every request is unconnected to the previous or following request • HTTP supports this via URL and HTTP method • Something like FTP does not – in FTP ‘where you are’ on the remote file system is implicit • State is maintained between requests – cd and then get • Two types of state: • Application state – should be at the client • Resource state – should be at the server • SOAP services also try to retain statelessness • SOAP envelope is able to contain everything needed in a discreet request • Although the term ‘stateful web service’ has become popular • Yuck! Back to Object orientation. Why? • Because by combining what the service handles (data/state) and how it handles it (method) leads to an Object oriented view – encapsulation of state and methods on that state

6. Web Feeds • Web Syndication is when one web site allows another web site to use/expose its content • The most common way this is done is using Web feeds. • These provide a summary of content available at the other site • Feed Aggregators (or Readers) allow a client to subscribe to a feed. • This is often done by the browser • But there are others e.g. iTunes for mp3 content • The reader will query the feed’s URI for any changes to the feed content, and notify the user if there are changes. • This is most commonly done using RSS (Really Simple Syndication) • XML specification for defining content available at an endpoint.

7. Atom • A syndication format and associated publishing protocol • Addresses some issues with RSS • RSS is underspecified in certain areas, for example: • Both for publishing and received content, there is no way to find out what the content is. • Is this plain text, or HTML or XHTML? • There is no registered MIME type for RSS • Not easy to understand individual entries in relation to an entire feed - Atom models both explicitly

8. Atom Syndication Format • An XML based specification: • A feed has metadata, e.g. • Title • Authors • updated date • Summary • Id • categories • Contains zero or more: entry elements • An entry contains similar metadata to the feed and also • A content element • The content element contains the actual content of the entry(!) e.g. text, html, xhtml, images, mp3s. • Content can also be referenced via a src attribute • So the client does not have to download it directly if it is large • As the author of the feed adds more entries, more entry elements are added to the feed element

9. Atom Feed Document feed entry title updated authors summary categories id … title updated authors summary categories id … 1 1..* 1 1 data content 1 1 e.g. html, xhtml, image src type

10. Example Atom Feed <?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <title>Example Feed</title> <link href=http://example.org/feedrel=“self”/> <updated>2003-12-13T18:30:02Z</updated> <author> <name>John Doe</name> </author> <id>urn:uuid:60a76c80</id> <entry> <title>My first entry</title> <id>urn:uuid:1225c695</id> <updated>2003-12-13T18:30:02Z</updated> <content type=“text”>Hello Atom.</content> </entry> </feed>

11. Atom Clients • In a typical scenario a human client will subscribe to a feed (e.g. a news feed or a blog) • The browser will remember the address of the feed and periodically poll the server to check if there are new entries in the feed. • This is typically done using an HTTP ‘conditional GET’ • The client asks for the feed IF it has changed • Uses HTTP headers ifModifiedSince or Etag • Conditional GETs save on bandwith and client and server processing • The Feed content may only be a partial list (if it’s long) • Use hypermedia as the engine of application state to link to prev and next (link rel=“prev”) • and the content may be referenced via URL (if it’s big)

12. Atom Publishing Protocol • Specifies how you create feeds and entries on the server • Uses HTTP for all operations • Representation of components uses XML • Top Level: service document • A service document contains workspaces • Workspaces are just logical groupings of collections • workspaces contain collections • collections contain entry documents and • have a URI • Categories - semantic grouping of content • accepted MIME types, e.g. text/html or image/* • Logically, a collection is an editable feed, i.e., a collection of entries that you manipulate through the publishing protocol.

13. Service Document service workspace 1 1..* url 1 1 collection entry uri Categories MIME types 1 1..*

14. Protocol Operations Retrieving a Service Document client server 1. HTTP GET to Service Document URI 2. HTTP 200 OK Service Document The Service Document contains URIs of collections

15. Protocol Operations Retrieving Collections client server 1. HTTP GET to Collection URI 2. HTTP 200 OK Atom Feed The returned Feed may contain all, or an ordered subset of entries

16. Protocol Operations Creating a new Entry client server 1. HTTP POST to Collection URI Atom Entry 2. HTTP 201 Created HTTP Location Header: URI of created Entry The HTTP Location: header points to the Newly created Atom Entry. This is now Part of the Collection (Feed)

17. Protocol Operations Retrieving an Entry client server 1. HTTP GET to Entry URI 2. HTTP 200 OK Atom Entry The Entry URI was returned to the client In the HTTP headers when it was created

18. Protocol Operations Edit an Entry client server 1. HTTP PUT to Entry URI Atom Entry 2. HTTP 200 OK

19. Protocol Operations Delete an Entry client server 1. HTTP DELETE to Entry URI 2. HTTP 200 OK

20. Atom as a generic RESTful API • Although designed primarily with syndication in mind • Atom provides a flexible, HTTP based, API for many types of application • Windows Live has an Atom Binding • Google Data Protocol - non-browser way of exchanging data • Access to • Analytics, Contacts, Calendar, Apps, Spreadsheets, YouTube and More • Open Archives Initiative (OAR) Object Reuse and Exchange • An RDF syntax for aggregating resources • Contains an Atom binding • Even in scientific (Grid/eScience) computing • Indiana University eChemistry projects

21. Atom Adoption • Not as widely adopted as hoped by its designers • Why? • One argument: • Browsers, browsers, browsers • More and more capability is available in browsers • Word processing, spreadsheets, etc. • Browsers use the DOM, Javascript • Preferred data interchange format: Javascript Object Notation (JSON) • JSON maps directly into Javascript data structures • No need to map from Atom Document format to browser language • For just sending and receiving data in a browser, JSON is much easier. • But no-one has designed a JSON publishing protocol yet so organizing/querying/searching etc data is not standardized.

22. URI Templates • A URI template is a structured string combining literals and variables into a URI • http://s3.amazon.com/{bucket-name}/{object-name} • This example shows an Amazon Simple Storage Service (S3) address as a URI template • In S3 each user has buckets into which they store objects • The bucket names and object names are different for every user but the structure of the URI is always the same - so you can define it using variables - bucket-name and object-name • To create a URI from the template, replace the variables inside the curly braces with your actual bucket names and object names • http://s3.amazon.com/mybucket/1234

23. …URI Templates • They are useful because • Using a RESTful approach, URIs are an important part of your API • You want your API to be easy to use and understand • You want your API to be machine processable • URI Templates: • Encourage designing understandable URIs • Encourage reuse of URI structures • Support the description of generic URI structures in the abstract • Are easy to program against e.g. using regular expressions

24. Web Application Description Language • The big thing about Web Services (SOAP etc) is that the XML dialects they use are fully machine processable, including service interfaces. • The Web Services model is to programmatically generate client code for a particular service. • Most Web 2.0 services are not described in a machine processable way • Instead you go to the site, read the documentation, and write a client by hand • Enter WADL - the Web Application Description Language • Not widely supported yet

25. WADL Target Apps • WADL addresses applications that: • Are based on existing Web architecture and infrastructure • Are platform and programming language independent • Promote re-use of the application beyond the browser • Enable composition with other Web or desktop applications • Require semantic clarity in content (representations) exchanged during their use

26. What does WADL model? • Sets of resources • Like a site map • Relationships between resources • Links between resources • Referencial and causal • Methods that can be applied to these resources • Resource representation formats • MIME types and Schema

27. WADL Document Structure application resources resource 1 1 1 1..* base url relative url 1 1 1..* 1..* response method params 1 1 fault code name name style type 1 1 1 1 request representation query params HTTP headers MIME type 1 1 MIME type Schema ref

28. WADL and URI Templates <application> <grammars> <include href=“myschema.xsd”/> </grammars> <resources base=“http://bank.com/”> <resource path=“accounts/{accountid}”> <param name=“accountid” style=“template” type=“xsd:int”/> … </resource> </resources> </application> Include XML schema Base URI relative URI template Describes The template

29. Google WADL Example http://www.google.co.uk/search?q=Obama <resources base=http://www.google.co.uk> <resource path=“search”> <method name=“GET”> <request> <param name=“q” style=“query” type=“xsd:string”/> </request> <response> <representation mediaType=“text/html”/> </response> </method> </resource> </resources>

30. WADL’s Future • Not widely supported • Why? • Do REST services want to adopt the code generation model of Web Services? • Does the simplicity of Web technologies require it? • Do Web Services really not require human intervention?