REST 11.07.2009Understanding and Using RESTful APIs

About MeDeveloping software for 15 yearsBulk of experience on enterprise-scale applicationsMicrosoft platform (mostly)KeyLimeTie

Developing software for 15 years

Bulk of experience on enterprise-scale applications

Microsoft platform (mostly)

KeyLimeTie

OverviewAlthough REST is 10 years old, APIs based on the REST model continue to become an integral part of the technology landscape. ProgrammableWeb.com lists 1051 RESTful APIs, 4422 Mashups.We’ll look atBasic REST ConceptsUsing RESTWADL

Basic REST Concepts

Using REST

WADL

Rest overview

REST OverviewAPIs based on the Representational State Transfer (REST) architecture dominate web 2.0 mash-up and social media development.There are a number of frameworks available that support the development of RESTful APIs (WCF, JAX-RS, Wicket, Zend)We are still missing an established mechanism for documentation and discovery and client-side tool support for rapid implementation.

REST OverviewREST-style architectures consist of clients and servers. Requests and responses are built around the transfer of "representations" of "resources". A resource is any entity that can be addressed in a URI (an account, an employee, a physical file)A representation of a resource is any information that captures the current or intended state of a resource. All information necessary to process and complete a request is contained within it.

ExampleResource (Twitter Public Timeline) http://twitter.com/statuses/public_timeline.xmlResource (Twitter User) http://twitter.com/users/petermorano.xml

REST OverviewREST-style architectures consist of clients and servers. Requests and responses are built around the transfer of "representations" of "resources". A resource is any entity that can be addressed in a URI (an account, an employee, a physical file)A representation of a resource is any information that captures the current or intended state of a resource. All information necessary to process and complete a request is contained within it.

Wait a MinuteIf this sounds a lot like the Web, it’s because the Web is a REST implementationRoy Fielding, who created REST, was also one of the principal authors of HTTP

REST BasicsThe REST architecture was designed around a few key principles: Use HTTP Methods (and Response Codes) Be Stateless and Cacheable Use Addressable Resources Support the transfer of Representations

Use HTTP Methods (and Response Codes)

Be Stateless and Cacheable

Use Addressable Resources

Support the transfer of Representations

REST BasicsThe REST architecture was designed around a few key principles:Use HTTP Methods (and Response Codes) Be Stateless and Cacheable Use Addressable Resources Support the transfer of Representations

Use HTTP Methods (and Response Codes)

Be Stateless and Cacheable

Use Addressable Resources

Support the transfer of Representations

HTTP MethodsMap to CRUD OperationsActionSQLHTTP MethodCreateInsertPostReadSelectGetUpdateUpdatePutDeleteDeleteDelete

URI ExamplesGEThttp://www.example.com/v1/employeesGEThttp://www.example.com/v1/employees/1824POSThttp://www.example.com/v1/employeesPUThttp://www.example.com/v1/employees/1513DELETEhttp://www.example.com/v1/employees/1222

REST BasicsThe REST architecture was designed around a few key principles: Use HTTP Methods (and Response Codes)Be Stateless and Cacheable Use Addressable Resources Support the transfer of Representations

Use HTTP Methods (and Response Codes)

Be Stateless and Cacheable

Use Addressable Resources

Support the transfer of Representations

Stateless and CacheableNo State Stored on the Server Every HTTP request executes in complete isolation on the server Easier to scale because of GET method

No State Stored on the Server

Every HTTP request executes in complete isolation on the server

Easier to scale because of GET method

REST BasicsThe REST architecture was designed around a few key principles: Use HTTP Methods (and Response Codes) Be Stateless and CacheableUse Addressable Resources Support the transfer of Representations

Use HTTP Methods (and Response Codes)

Be Stateless and Cacheable

Use Addressable Resources

Support the transfer of Representations

ResourcesAny THING – person, concept, artifact Anything you can point to Explicit Request and Response – No State

Any THING – person, concept, artifact

Anything you can point to

Explicit Request and Response – No State

REST BasicsThe REST architecture was designed around a few key principles: Use HTTP Methods (and Response Codes)Be Stateless and Cacheable Addressable ResourcesSupport the transfer of Representations

Use HTTP Methods (and Response Codes)

Be Stateless and Cacheable

Addressable Resources

Support the transfer of Representations

RepresentationsA serializable description of a Resource Resources are modifiable through Representations XMLJSONBinary Formats (jpg, gif, mpeg)

A serializable description of a Resource

Resources are modifiable through Representations

XML

JSON

Binary Formats (jpg, gif, mpeg)

REST ProsCacheableScalableDifferent RepresentationsHuman Readable ResultsLightweight

REST ConsMust be HTTPNo Atomic TransactionsNo Standards for security except HTTPSNo Standardized Discovery

REST vs. SOAPUnlike SOAP-based web services, there is no "official" standard for RESTful web service. Though not a standard, a RESTful implementation uses standards like HTTP, URL, XML, GIF, etc.

REST vs. SOAPSOAPProtocol Verbose PayloadEnvelopeNot easily readableRequires Development ToolsUses POST MethodSupports TransactionsStandardized DiscoveryWSDLRESTArchitectureLightweight PayloadPostcardHuman Readable ResultsEasy to work with, Brower-testableGET Method supports cachingNo TransactionsDiscoveryWADL?

Protocol

Verbose Payload

Envelope

Not easily readable

Requires Development Tools

Uses POST Method

Supports Transactions

Standardized Discovery

WSDL

Architecture

Lightweight Payload

Postcard

Human Readable Results

Easy to work with, Brower-testable

GET Method supports caching

No Transactions

Discovery

WADL?

USING Rest

USING RESTThink of a REST API as another data sourceDetails depend on the language, but there are common steps:Serialize the representation (if PUT or POST)Format the URI (parameters, variables)Encode Authentication into the HeaderMake CallDeserialize Response

Serialize the representation (if PUT or POST)

Format the URI (parameters, variables)

Encode Authentication into the Header

Make Call

Deserialize Response

USING RESTThree basic options for consuming RESTful APIsUse the service’s toolkit (not always available)Community-built library/wrappercode.google.comwww.codeplex.comCode your own implementation

Use the service’s toolkit (not always available)

Community-built library/wrapper

code.google.com

www.codeplex.com

Code your own implementation

Community BuiltUpside Ready to useDownsideIt’s not your codeYou may be waiting for the library to become available.Enterprise clients may have concerns

Ready to use

It’s not your code

You may be waiting for the library to become available.

Enterprise clients may have concerns

Writing Your OwnUpside You know the codeDownsideManual Discovery ProcessImplementation can be tedious

You know the code

Manual Discovery Process

Implementation can be tedious

ToolsTools for testing RESTful APIsCurlEclipse Http4eFiddler Your Browser (limited)

Curl

Eclipse Http4e

Fiddler

Your Browser (limited)

WADL

WADLWeb Application Discovery Language (WADL)Created in 2005 by Marc Hadley of Sun MicrosystemsSubmitted to W3C on 8/31/2009REST’s Answer to WSDLSpecification: https://wadl.dev.java.net/

What WADL Gets YouReduced Errors in DiscoveryOpportunities for Code GenerationSpend more time building your application and less time implementing APIs

So Where Is It?Currently in Submission to W3CAPI Providers are slow to adopt, so tool providers are slow to implementThere are projects underway to generate code from WADL, and at least one tool that helps in creating WADL

WADL DemoProject on code.google.comOnline Version: http://tomayac.de/rest-describe/latest/RestDescribe.html

Referenceshttp://en.wikipedia.org/wiki/Representational_State_Transferhttp://weblogs.java.net/blog/mhadley/archive/2005/05/introducing_wad.htmlhttp://blog.tomayac.de/index.php?date=2007-05-23RESTful Web Services – Richardson, Ruby – O’Reilly Press