Restful web services rule financial

Confidential

RESTful Web Services

Grzegorz Borkowski

Introduction

REST principles

Designing RESTful API

Miscellaneous

Implementions and Frameworks

Implementing RESTful API

RESTful Web ServicesAgenda

2© Rule Financial 2011

REST principles


Miscellaneous





Introduction

Introduction


Materials The most recommended reading:

Materials - Richardson, Leonard; Ruby, Sam (2007-05), RESTful Web Services, O'Reilly (warning: code examples are written in Ruby!)

Introduction


REST origins REST = Representational state transfer - a style of software architecture The term representational state transfer was introduced and defined in 2000 by Roy Fielding in his doctoral

dissertation REST = applying HTTP principles to the software architecture RESTful = conforming to the REST priniciples. → RESTful Web Services

Why has HTTP got so popular? Because of simplicity. Probably every programming language supports HTTP - because it’s easy! Compare to SOAP – SOAP is much more complicated. Internet. Internet is efficient, scalable, easy to use… we want our software to be like the Internet!

SOAP – alternate approach to web services. To better understand REST, it's helpful to compare it to SOAP. REST is a simpler alternative to SOAP, a simpler way to build web services. Compare especially WSDL!

Introduction


An HTTP GET request for http://www.oreilly.com/index.htmlGET /index.html HTTP/1.1Host: www.oreilly.comUser-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.12)...Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,...Accept-Language: us,en;q=0.5Accept-Encoding: gzip,deflateAccept-Charset: ISO-8859-15,utf-8;q=0.7,*;q=0.7Keep-Alive: 300Connection: keep-alive

The response to an HTTP GET request for http://www.oreilly.com/index.htmlHTTP/1.1 200 OKDate: Fri, 17 Nov 2006 15:36:32 GMTServer: ApacheLast-Modified: Fri, 17 Nov 2006 09:05:32 GMTEtag: "7359b7-a7fa-455d8264Content-Length: 43302Content-Type: text/htmlKeep-Alive: timeout=15, max=1000Connection: Keep-Alive <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><title>oreilly.com -- Welcome to O'Reilly Media, Inc.</title>...

Introduction


Miscellaneous





REST principles

REST principles


REST keywords: Resources Addressability Statelessness Uniform API Representations Cacheability Connectedness and discoverability

REST principles


Resource Every data or abstraction which can be created/updated/retrieved/removed and somehow represented, and is

addressable. Web page is a resource; but also a blog post, a comment, a cart, a cart item etc.

REST principles


Addressability Why addressability is important?

Bookmarking sending links resource-level authorization

Compare FTP, JSF 1.x, most of poorly written Ajax applications, Flash-based applications – they are not addressable. URIs vs URLs vs URNs

URI doesn't have to be URL. For example, XML namespace is an URI, but it's not an URL URLs that point to the same resource:

http://mylib.example.com/releases/1.1http://mylib.example.com/releases/1.2http://mylib.example.com/releases/latest at this time, it can be the same as 1.2

URIs of the single resources vs URIs of the resource lists/querieshttp://mylib.example.com/releases/ list of all releaseshttp://mylib.example.com/releases/?majorVersion=1http://mylib.example.com/releases/1.2

REST principles


Addressability – cont. Permanent URIs vs Readable URIs (vs Hybrid URIs)

“Clean URLs” - http://en.wikipedia.org/wiki/Clean_URLs - advantages:

SEO

user experience

hide underlying technology (index.jsp, index.php, index.aspx) mod rewrite, UrlRewriteFilter

Note: percent-encoding URL-encoding – URI specification, closely related to HTTP (” ” -> ”%20”) Form encoding – part of HTML specification for submitting forms (” ” -> ”+”)

as a query string (part of URL!) in GET requests, as a body in POST requests

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

REST principles


Statelessness Every request is independent of previous one No server-side sessions, conversation state is kept on the client side only Advantages:

SimplicityScalabilityAddressability

Application (conversation) state vs resource state Resource state is the same for all clients/applications Application (conversation) state is client-specific

REST principles


Uniform API Uniform operations: CRUD

POST CreateGET Read (retrieve single resource, or query to get list of matches)PUT Update (or Create)DELETE Delete

SOAP is more like Java/.NET/etc – no uniform API. REST is more like SQL – uniform API (insert, select, update, delete). Special meaning of POST („Overloaded POST”) trigger some algorithm/procedure/operation note: PUT/DELETE over POST (for example for HTML 4.x forms)

Safe and indempotent operations Take care to keep PUT indempotent (eg. Don't increment value in PUT)Safe – e.g. safe for webcrawlers.Safe and indempotent calls are great for unreliable networks – if request times out, just resend it. Why it's important – example of Google Accelerator (2005)

REST principles


Uniform API Uniform response codes

1xx - info2xx - ok3xx - redirect4xx – client error5xx – server error

Uniform headers, e.g.:Accept-Encoding: gzip,deflate

Last-Modified: Fri, 17 Nov 2006 09:05:32 GMT

Content-Type: text/plain

(but you are not limited to the standard headers, you can use your own ones)

Compare to RPC

REST principles


Representations The same resource, but different representations - content types:

HTML, XHTMLXMLJSONForm-encoded (application/x-www-form-urlencoded)

binary (PDF, JPG,...)Base64Plaintext

Content negotiation using headers or the representation specified in the URI (…/projects/12.xml - …/projects/12.json)

Short/medium/long representation, e.g.:– Users list for dropdowns, only id and label – short representation– Users list with details – medium representation– Users list with related projects, tasks, absences etc. - long representation

REST principles


Cacheability All HTTP clients are allowed to cache resources Caching controlled by standard headers (Uniform API!)

– HTTP 1.0: Expires, Last-Modified, If-Modified-Since– HTTP 1.1: Cache-Control, Etag, If-None-Matches

Cache forever and never ask again – great value for versioned resources Cache and ask whether it has changed (Conditional GET) IE problems for Ajax requests – broken caching, use the random element in URL

Connectedness Navigation from one resource to related resources by links Discoverability

Introduction

REST principles

Miscellaneous






Designing RESTful APIRESTful web service example


Simple RESTful web service Amazon S3 (Simple Storage Service) A service for reliable storage of objects (files) Two types of resources

– Buckets– Objects

API:

GET HEAD PUT DELETE

The bucket list/

List your buckets - - -

A bucket/{bucket}

List the bucket’s objects

- Create the bucket Delete the bucket

An object/{bucket}/{object}

Get the object’s valueand metadata

Get the object’s metadata

Set the object’s valueand metadata

Delete the object



Designing the read-only API Design resources Design representations served by the service Specify supported methods Specify caching

Designing RESTful APIExercise


Design the read-only market data information service for traders Service should deliver information about:

Exchanges (name, location, public holidays, …) Indices (name, current value, past values) Stocks (name, fundamental data, current price, past prices) Derivatives Fx pairs

Design Resources Their addresses Supported methods Representations



Designing the read-write API Design resources Design representations served by the service Design accepted incoming representations Specify supported methods Specify caching Security

Authentication (preferred stateless: keep authentication state on the client side, reauthenticate on each request) Authorization

Error handling

Note: Basic authentication Server returns code and header:

401 Authorization Required

WWW-Authenticate: Basic realm=„Realm name"

Client sends (with each request) header:Authorization: Basic Base64Encoded(username:password)

Introduction

REST principles






Miscellaneous

Miscellaneous


Versioning Versioning

Versioning of resources – e.g. http://myservice.example.com/rest/customers/11235.4 Versioning of API – e.g. http://myservice.example.com/rest/v1/customers/

Miscellaneous


HTTP – additional capabilities Compression

Accept-Encoding: gzip,deflate

Async requests

Response code: 202 Accepted

„jobs”

Conditional PUT Expect reponse code: 100 Continue

Introduction

REST principles


Miscellaneous







Client side requirements Support for SSL/TLS

Support PUT, DELETE, HEAD, not only GET and POST

Support manipulation of request headers

Access to response headers and status code

Support proxies

Support compression

Support caching

Support authentication mechanisms (basic, digest, wsse, o-auth)

Support redirects (3xx)

Java examples java.net. HttpURLConnection

Apache HttpClient

Restlet Client



Server side requirements - all as client side, plus boiler-plate code reducing features URI Templates with data conversion and binding: /project/{projectName}/tasks/{taskId}

content-negotiation

PUT/DELETE over POST

Body parsing, conversion and binding (plain, form-encoded, json, xml)

data validation

Java examples JAX-RS

Restlet

Spring MVC

Introduction

REST principles


Miscellaneous





Confidential

It’s time to code something!

Technology

Restful web services rule financial