rest-based web services (i) · rest-based web services (i) helen paik school of computer science...

REST-based Web Services (I)

Helen Paik

School of Computer Science and EngineeringUniversity of New South Wales

Resources:

RESTful Web Services by L. Richardson and S. Ruby, O’Reilly(http://oreilly.com/catalog/9780596529260)

ICSOC 2008 Summer School session on REST-based Services – article: How to get a cupof coffee by Jim Webber (http://www.infoq.com/articles/webber-rest-workflow)

Building Web Services the REST Way, By Roger L. Costello –http://www.xfront.com/REST-Web-Services.html

Acknowledgement: The slides are adapted from ‘RESTful Web Services’ chapters 4, some of the slides are from the previoussessions prepared by Dr. Adnene Guabtni and Dr. Sherif Sakr.

Week 6H. Paik (CSE, UNSW) REST Week 6 1 / 54

http://oreilly.com/catalog/9780596529260

http://www.infoq.com/articles/webber-rest-workflow

http://www.xfront.com/REST-Web-Services.html

What is REST and Why REST

REST is an architectural style guide of building networked systems. Itis popularised as a guide to build modern distributed applications onthe Web

Drivers of RESTinteroperability between heterogeneous systems (i.e., integratingapplications that are built using different languages and run ondifferent platforms) ... Think News sitesrise of different client devices ... not just phones. Think iCar, iWatchscailability ... a (potentially) large number of clientsthis kind of broad integration is only possible if the way the involvedservices (providers/consumers) interact with each other is based on aset of simple, consistent and reliable principles

REST itself is not an official standard specification or even arecommendation. It is just a “design guideline” for building a system(or a service in our context) on the Web

H. Paik (CSE, UNSW) REST Week 6 2 / 54

REST philosophy: Resource-Oriented Architecture

Main objective of REST is to expose resources on a networked system (theWeb)

What is a Resource?

A resource is anything that is important enough to be referencedas a ‘thing’ in itself. If you want to create a hypertext link to it,make or refute assertions about it, retrieve or cache arepresentation of it, include all or part of it by reference intoanother representation, annotate it, or perform other operationson it, then you should make it a resource. 1

Usually, a resource is something that can be stored on a computer andrepresented as a stream of bits: a document, a payment, or the result ofrunning an algorithm, a photo, a resume, an employee, a blog posting ...

1The text is from the O’Reilly book RESTful Web ServicesH. Paik (CSE, UNSW) REST Week 6 3 / 54

REST philosophy

In REST, everything starts and ends with resources.

What is a Resource?

A resource is a thing that:

is unique (i.e., can be identified uniquely)

has at least one representation,

has one or more attributes beyond ID

has a potential schema, or definition

can provide context

is reachable within the addressable universe


Resource Representation(s)


But before we move on ...

Let us clear up a few things about URI, URL and URN

A uniform resource identifier (URI) is a string of characters usedto identify a name or a resource in a network (typically WorldWide Web)

Why do we need it? ...

URI:

URI schemes specify an exact syntax (i.e., what it looks like) andassociated protocols (i.e., how it is used) for each URI ...

URI schemes ? (http://en.wikipedia.org/wiki/URI_scheme)

URI examples (with different schemes):ftp://ftp.springer.de/pub/tex/latex/llncs/latex2e/instruct/editors/editors.pdf

URN:ISBN:952-10-0093-7

http://www.cse.unsw.edu.au


http://en.wikipedia.org/wiki/URI_scheme

But before we move on ...

URL is a URI.

in addition to being a resource identifier, it specifies the means forfinding it (i.e., locating/obtaining it over the network)

common URI schemes for URL = http:, ftp:, mailto:, file:

should give you ’Not Found’ error (i.e., unable to locate)

URN is a URI.

it uses a URI scheme called URN to name resources (similar tonaming a person)

examples (global URN schemes):urn:isbn:0451450523 (The Last Unicorn (1968 book), book number)urn:isan:0000-0000-9E59-0000-O-0000-0000-2 (Spider-Man (2002film), audiovisual number)urn:ietf:rfc:2648 (IETF’s RFC 2648)

should not give you ’Not Found’ error - it is not a locator


Resource ID, Representations and Descriptions

Let’s say a company exposes the following URLs as pointers to theiremployees:

http://www.example.com/people/alice (the homepage of Alice)

http://www.example.com/people/bob (the homepage of Bob)

Strictly speaking, in the above URLs, we are mixing up the identity of aresource and descriptions/representations of it ... This may not bedesirable, if we want to manage (and build services on) resources that arenot Web pages ... such as people, products, places, ideas/concepts, etc.

Using http://www.example.com/people/alice as both the ID, as well as aWeb document does not quite work ... e.g.,

How do we answer a question: How old ishttp://www.example.com/people/alice ?

How to represent that Bob may not like the look of the homepage, butfancy the person Alice.


Resource ID, Representations and Descriptions

So two URIs are needed, one for Alice, one for the homepage. Or maybemore than two if Alice should have multiple representations: e.g., a HTMLdocument, a photo of her, a PDF document.

Using URIs, it is possible to identify both a thing (which may exist outsideof the Web) and a Web document describing the thing.

Possible solutions:

http://www.example.com/about#alice (Identifier for Alice, the person)

http://www.example.com/id/alice (Identifier for Alice, the person)

- redirected to http://www.example.com/people/alice (Alice’s homepage)

- redirected to http://www.example.com/data/alice (XML document with

description of Alice)


Origins of REST

REST is an acronym standing for Representational State Transfer.

First introduced by Roy T. Fielding in his PhD dissertation”Architectural Styles and the Design of Network-based SoftwareArchitectures”

http://www.ics.uci.edu/∼fielding/pubs/dissertation/top.htm

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

He proposed REST as a design guide for a modern Web softwaresystem by applying ‘a set of architectural style constraints’ to theelements within the Web architecture

REST is client-server where a representation of the resource isexposed to the client application.

always assumes a disconnected system - interface/contract


REST principles (I): Resource Identification

Resources are identified by a URI (Uniform Resource Identifier)

http://www.example.com/software/release/1.0.3.tar.gz

A resource has to have at least one URI

Most known URI type are URL and URNURN (Uniform Resource Name)

urn:isbn:0-486-27557-4 (a specific edition of Shakespeare’s play Romeoand Juliet)

URL (Uniform Resource Locator)

file:///home/tommy/plays/RomeoAndJuliet.pdf

Every URI designate exactly one resource

cf. what about:http://www.example.com/software/releases/1.0.3.tar.gzhttp://www.example.com/software/releases/latest


REST principles (II): Addressability

An application is ’addressable’ if it exposes its data set asresources (i.e., usually an infinite number of URIs)

Filesystem on your computer is addressable system

The cells in a spreadsheet are addressable (cell referencing)

Google is addressable: a resource’http://www.google.com.au/search?q=unsw’

you can bookmark, use it as link in a program, you can email, etc.

REST advocates addressability as a main feature of its principles

This seems natural, the way the Web should work, but manyapplications don’t work this way all the time


REST principles (III): Statelessness

Stateless means every HTTP request happens in a completeisolation. When client makes an HTTP request, it includesnecessary information for the server to fulfil the request


REST principles: Statelessness

There are many Web sites that expects you to make requests ina certain order: A, B, then C. – There are sections in the systemwhere you can only reach via building up certain ‘interactionstate’ on the server ...



Stateless is good !! - scalable, easy to cache, addressable URIcan be bookmarked (e.g., 10th page of search results)

HTTP is by nature stateless

We do something to break it

the most common way to break it is ’HTTP sessions’

the first time a user visits your site, he gets a unique string thatidentifies his session with the site

http://www.example.com/forum?PHPSESSIONID=27314962133the string is a key into a data structure on the server and the datastructure that contains the stateall interactions assume the key to be available to manipulate the dataon the server



What counts as ‘state’ exactly? application state vs. resource state

Think a Flickr.com-like web site ... you will add photos, rename photos,share them with friends, etc. – what would ‘being stateless’ mean here?

Two kinds of statesphotos are resourcesclient applications access those resources per their application logic

resource state live on the server (i.e., photos are stored on the server)individual client application states (i.e., photos John clicked on)should be kept off the serverconsider the application state as data that could vary by client, andper request.

e.g., Google’s resources – indexed web pages. Client application state –your query and your current page (different for every client because eachclient takes a different ’path’ to their current state)



Statelessness in REST applies to the client application state

REST principle says: URI should contain the necessary state tohandle the request within the request itself, whether as part ofthe URI, query-string parameters, body, or headers. The URIuniquely identifies the resource and the body contains the state(or state change) of that resource.

i.e., every REST request should be totally self-descriptivea RESTful service requires that the application state to stay on theclient sideserver does not keep the application state on behalf of a clientclient transmit the state to the server for every request that needs it

Resource state is the same for every client and its state is managed on theserver.



e.g., being client-aware (i.e., stateful): Say every client has to send an APIkey to a server to access an operation so that the server can restricts youto a certain number of requests a day ...

the number of requests made is client state (different for every client)

but the server will not trust the client to self-report the its statehonestly ...

so the ’count’ for individual client will be stored on the server - i.e.,creating a server-side client state

Consequences: scalability is not as good ...

if the service is distributed across multiple machines, every machine ina cluster needs to know client A is on request number X and so on.

or load balancer needs to make sure that every client A request goesto the same machine

Roy Fielding says: Like most architectural choices, the stateless constraintreflects a design trade-off.


REST principles (IV): Resource Representations

A resource needs a representation for it to be sent to the client

a representation of a resource - some data about the ’current state’ ofa resource (i.e., a list of open bugs)

a list of open bugs – in XML, a web page, comma-separate-values,printer-friendly-format, etc.

when a representation of a resource may also contain metadata aboutthe resource (e.g., books: book itself + metadata such ascover-image, reviews, stock-level, etc.)

Representation can flow the other way too: a client send a new or updated’representation’ of a resource and the server creates/updates the resource.


REST principles: Resource Representations

Deciding between multiple representations

Option 1.

Have a distinct URI for each representation of a resource:

http://www.example.com/release/104.en (English)http://www.example.com/release/104.es (Spanish)http://www.example.com/release/104.fr (French)

This also meets the addressability and statelessness principles in that theserver knows all info necessary for the server to fulfil the request


REST principles: Resource Representations

Deciding between multiple representations

Option 2.

Use HTTP HEAD (metadata) for content negotiation:

expose, e.g., http://www.example.com/release/104client HTTP request contains Accept-Language

Other types of request metadata can be set to indicate all kinds of clientpreferences, e.g., file format, payment information, authenticationcredentials, IP address of the client, caching directives, and so on.

Option 1 or 2 are both acceptable REST-based solution ... but addressable URI option ispreferred. e.g., Say you want to use a HTML page translation service which accepts URI... which representation offer will give you the most flexibility?


REST principles (V): Links and Connectedness

In REST, resource representations are hypermedia: resource(data itself) + links to other resources

e.g., Google Search representation:


REST principles: Links and Connectedness

R. Fielding talks about: “Hypermedia as the engine of application state”

The current state of an HTTP ‘session’ is not stored on theserver as a resource state, but tracked by the client as anapplication state, and created by the path the client takesthrough the Web. The server guides the client’s path by servinghypermedia: links and forms inside resource representations.

The server sends the client guidelines about which states are near andcurrent one.


REST principles: Links and Connectedness

Connectedness in REST

All three services expose the same functionality, but their usability increasestowards the right

Service A is a typical RPC-style, exposing everything through a single URI. Neitheraddressable, nor connected

Service B is addressable but not connected; there are no indication of therelationships between resources. A hybrid style ...

Service C is addressable and well-connected; resources are lined to each other inways that make sense. A fully RESTful service


REST principles (VI): Uniform Interface

REST Uniform Interface Principle has 4 HTTP main operationson resources

Discuss input/output of the following.

PUT: Create a new resource (new URI) or update a resource (existing URI)

GET: Retrieve a representation of a resource.

POST*: Modify the state of a resource. POST is a read-write operationand may change the state of the resource and provoke side effects on theserver. Web browsers warn you when refreshing a page generated withPOST.

DELETE: Clear a resource, after the URI is no longer valid

HEAD and OPTIONS

Similar to the CRUD (Create, Read, Update, Delete) databases operations

*POST: a debate about its exact best-practice usage ...H. Paik (CSE, UNSW) REST Week 6 25 / 54

REST principles: Uniform Interface



REST Uniform Interface, if properly followed, gives you two properties:

being Safe

Read-only operations ... The operations on a resource do not change anyserver state. The client can call the operations 10 times, it has no effecton the server state.

(like multiplying a number by 1, e.g., 4x1, 4x1x1, 4x1x1x1, ...)

being Idempotent

Operations that have the same “effect” whether you apply it once or morethan once. An effect here may well be a change of server state. Anoperation on a resource is idempotent if making one request is the same asmaking a series of identical requests.

(like multiplying a number by 0, e.g., 4x0, 4x0x0, 4x0x0x0, ...)H. Paik (CSE, UNSW) REST Week 6 27 / 54


Safety and Idempotence

GET: safe

HEAD and OPTION: safe

PUT: - idempotent

If you create a resource with PUT, and then resend the PUT request,the resource is still there and it has the same properties you gave itwhen you created it.If you update a resource with PUT, you can resend the PUT requestand the resource state won’t change again

DELETE: - idempotent

If you delete a resource with DELETE, it’s gone. You send DELETEagain, it is still gone !



Why Safety and Idempotence matter

The two properties let a client make reliable HTTP requests over anunreliable network.

Your GET request gets no response? make another one. It’s safe.

Your PUT request gets no response, make another one. Even if yourearlier one got through, your second PUT will have no side-effect.

There are many applications that misuse the HTTP uniform interface. e.g.,

GET https://api.del.icio.us/posts/delete

GET www.example.com/registration?new=true&name=aaa&ph=123

Many expose unsafe operations as GET and there are many use of POST operation

which is neither safe nor idempotent. Repeating them has consequences ...



Why Uniform Interface matters

Uniformity

The point about REST Uniform Interface is in the ’uniformity’: that everyservice use HTTP’s interface the same way.

It means, for example, GET does mean ’read-only’ across the Web nomatter which resource you are using it on.

It means, we do not use methods in place of GET like doSearch orgetPage or nextNumber.

But, it is not just using GET in your service, it is about using it theway it was meant to be used.


Brief Recap of REST principles

Resources:

Resource: Any *thing* (noun) that is worthy of being given a uniqueID and be accessible via client. The ID is given in form of (....)

The state of a resource is managed by (.....)

Resources must have (......) to be ’transmitted’ to client

Give an example of a resource and its representations ?



Uniform Interface: Uniform ‘verbs’ that go with the resources (noun)

Given a resource (coffee order): a representation in XML

<order xmlns="urn:starbucks">

<drink>latte</drink>

</order>

What does the following operations mean (and what do they return)?

POST /starbucks/orders

GET /starbucks/orders/order?id=1234

PUT /starbucks/orders/order?id=1234

DELETE /starbucks/orders/order?id=1234



Connectedness/Links: Resources may contain links to other resources

e.g., Order resource is linked to Payment resource

In response to POSTing an order

201 Created

Location: /starbucks/orders/order?id=1234

Content-Type: application/xml

Content-Length: ...

<order xmlns="urn:starbucks">

<drink>latte</drink>

<link rel="payment" href="/starbucks/payments/order?id=1234"

type="application/xml"/>

</order>

Both forward/backward links, when possible (e.g., order having ’cancel/delete’ link)


REST Recap - Hypermedia


REST Recap - Satefy, Idempotence


Popular Resource Representation Formats

XML (RSS, ATOM, ...)

Standard textual syntax for semi-structured data

Managed within several standard tools like XML Schema, DOM,SAX, XPath, XSLT, XQuery, ...

<animals>

<dog>

<name>Rufus</name>

<breed>labrador</breed>

</dog>

<dog>

<name>Marty</name>

<breed>whippet</breed>

</dog>

<cat name="Matilda"/>

</animals>


Popular Resource Representation Formats

JSON (JavaScript Object Notation)2

Data interchange format derived from the JavaScript programminglanguage for representing simple data structures (name/value pairs,arrays and other objects)

Popularised by AJAX (Asynchronous JavaScript + XML).

{ animals:{dog:[

{ name:’Rufus’,

breed:’labrador’ },{ name:’Marty’,

breed:’whippet’ }],

cat:{ name:’Matilda’ }}

}2http://json.org/example.html


http://json.org/example.html

One API for All

One resource, multiple representations (it is the client’s choice):


Building REST Web services

In theory: REST does not require a specific client or server-side frameworkin order to write your Web services. All you need is a client or server thatsupports the HTTP protocol.

choose a language of your choice

you do not need a big server infrastructure (HTTP/Web servers areenough)

e.g., In Java: You’d use servlets and override doGet(), doPost(), doPUT()and doDelete()

URLs contains: servlet path + path info (all you need to process arequest in REST)

You could use a third-party library for generating specific content type(CSV, JSON or XML, etc.) or use Strings concatenations for simpleresponses.



The basic pieces you need to create a RESTful service:

a Path - the path to the service

a request method (e.g., GET, POST)

the response types from the service

e.g., A quick look at a simple servlet that supports GET (and XML, CSVand JSON resource formats)

A servlet is mapped to /places/sydney/*

GET returns some interesting places in Sydney

Default representation is XML, but other format can be added in thepath info: JSON and CSV

Uses http://www.JSON.org/java/index.html for the JSONencoding


http://www.JSON.org/java/index.html

Building REST Web services (Implementing an XML reply)


Building REST Web services (Implementing a CSV reply)


Building REST Web services (Implementing a JSON reply)


Building REST services

In reality ... it would still be nice to have some support (a framework)

Having a framework can help reduce boilerplate-type coding

In Java, standard specification is: JAX-RS(http://jcp.org/en/jsr/detail?id=311)

Apache CXF - http://cxf.apache.org/docs/jax-rs-basics.html

Jersey - the JAX-RS Reference Implementation from Sun.

RESTEasy - JBoss’s JAX-RS project.

Restlet - probably the first REST framework, which existed prior toJAX-RS.


http://jcp.org/en/jsr/detail?id=311

Building REST services: JAX-RS

http://java.dzone.com/articles/putting-java-rest

JAX-RS uses Java annotations. Annotate your class with:

@Path: to indicate the relative URI path you are interested in,@GET, @POST, @PUT, @DELETE, or @HEAD: to indicate whichHTTP method you want dispatched to a particular method.@Produces: to indicate the response type

01. @Path("/orders")

02. public class OrderEntryService {03. @GET

04. @Produces(MediaType.TEXT_PLAIN)

05. public String getOrders() { return "There!";}06. }

Given “GET http://xxx.xxx.xx/orders”, JAX-RS would dispatch the HTTPrequest to getOrders() and return the content getOrders() produces.


http://java.dzone.com/articles/putting-java-rest


We may want to limit the size of the result set returned.

“GET http://xxx.xxx.xx/orders?size=50”

To extract this information from the HTTP request, use a @QueryParamannotation:



04. public String getOrders(@QueryParam("size")

05. @DefaultValue("50") int size)

06. { ... method body ... }09. }

@QueryParam will pull the “size” query parameter from the incoming URL

The @DefaultValue injects the default value of ”50”.



Exposing a single order as a resource:

“GET http://xxx.xxx.xx/orders/1234”

Using Path Parameters:



04. @Path("{id}")05. public String getOrder(@PathParam("id") int orderId) {06. ... method body ...

07. }08. }

To use @PathParam or @QueryParam: let’s not put resource identity within a queryparameter when it really belongs as part of the URI path itself.



Content-Type: the service produces HTTP response, so the content typemust be set first.

For example, let’s say our getOrders() method actually returns an XMLstring.:



04. @Path("{id}")05. @Produces("application/xml")

06. public String getOrder(@PathParm("id") int orderId)

07. {... method body }08. }



JAX-RS understands the Accept header and will use it when dispatching.

Content Negotiation:

Accept: text/html,application/xhtml,application/xml;q=0.9,*/*;q=0.8the client prefers: html or xhtml (q is 1 by default), raw XML second, and any othercontent type third



04. @Path("{id}")05. @Produces("application/xml")

06. public String getOrder(@PathParm("id") int orderId) {...}07. @GET

08. @Path("{id}")09. @Produces("text/html")

10. public String getOrderHtml(@PathParm("id") int orderId) {...}11. }

“GET http://.../orders/1234” with the above Accept would match getOrderHtml().



Content Marshalling: e.g., code to convert a list of orders to an XMLstring that the client can consume.

The JAX-RS specification has some required built-in marshallers (e.g.,JAXB annotated classes)

@XmlRootElement(name="order")

public class Order {@XmlElement(name="id")

int id;

@XmlElement(name="customer-id")

int customerId;

@XmlElement("order-entries")

List<OrderEntry> entries; ...

}

@Path("/orders")

public class OrderEntryService {@GET

@Path("{id}")@Produces("application/xml"

public Order

getOrder(@PathParm("id") int orderId) {...}}

JAX-RS sees the Content-Type (application/xml) and the JAXB annotated Order classand will automatically use JAXB to write the Order object to the HTTP output



Response Codes and Custom Responses: HTTP spec defines what HTTPresponse codes should be on a successful request. (e.g., GET = 200, OK;PUT = 201, CREATED)

JAX-RS returns the same default response codes.

Sometimes, however, you need to specify your own response codes (or addspecific headers or cookies to your HTTP response).

@Path("/orders")


@Path("{id}")public Response getOrder(@PathParm("id") int orderId)

{Order order = ...;

ResponseBuilder builder = Response.ok(order);

builder.expires(...some date in the future);

return builder.build();

}}



Exception Handling: RuntimeException/WebApplicationException class

It can take an HTTP status code or a Response object as one of itsconstructor parameters.

@Path("/orders")


@Path("{id}")@Produces("application/xml")

public Order getOrder(@PathParm("id") int orderId) {Order order = ...;

if (order == null) {ResponseBuilder builder = Response.status(Status.NOT FOUND);

builder.type("text/html");

builder.entity("<h3>Order Not Found</h3>");

throw new WebApplicationException(builder.build());

}return order;

}}


rest-based web services (i) · rest-based web services (i) helen paik school of computer science...

Documents