Unerstanding and Using RESTful APIs

REST 11.07.2009Understanding and Using RESTful APIs

About Me

•Developing software for 15 years

•Bulk of experience on enterprise-scale applications

•Microsoft platform (mostly)

•CTO at KeyLimeTie

Overview

Although 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 at

• Basic REST Concepts• Using REST• WADL

REST OVERVIEW

REST Overview

APIs 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 Overview

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

Example

Resource (Twitter Public Timeline)http://twitter.com/statuses/public_timeline.xml

Resource (Twitter User) http://twitter.com/users/petermorano.xml

REST Overview

REST-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 Minute

If this sounds a lot like the Web, it’s because the Web is a REST

implementation

Roy Fielding, who created REST, was also one of the principal authors of HTTP

REST Basics

The 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

REST Basics

The 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

HTTP Methods

Action

Create

Read

Update

Delete

SQL

Insert

Select

Update

Delete

HTTP Method

Post

Get

Put

Delete

Map to CRUD Operations

URI Examples

GET

GET

POST

PUT

http://www.example.com/v1/employeeshttp://www.example.com/v1/employees/1824http://www.example.com/v1/employeeshttp://www.example.com/v1/employees/1513

DELETEhttp://www.example.com/v1/employees/1222

REST Basics

The 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

Stateless and Cacheable

• No State Stored on the Server

• Every HTTP request executes in complete isolation on the server

• Easier to scale because of GET method

REST Basics

The 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

Resources

• Any THING – person, concept, artifact

• Anything you can point to

• Explicit Request and Response – No State

REST Basics

The REST architecture was designed around a few key principles:

• Use HTTP Methods (and Response Codes)

• Be Stateless and Cacheable

• Addressable Resources

• Support the transfer of Representations

Representations

• A serializable description of a Resource

• Resources are modifiable through Representations

• XML

• JSON

• Binary Formats (jpg, gif, mpeg)

REST Pros

Cacheable

Scalable

Different Representations

Human Readable Results

Lightweight

REST Cons

Must be HTTP

No Atomic Transactions

No Standards for security except HTTPS

No Standardized Discovery

REST vs. SOAP

Unlike 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. SOAP

SOAP

•Protocol

•Verbose Payload• Envelope

•Not easily readable

•Requires Development Tools

•Uses POST Method

•Supports Transactions

•Standardized Discovery• WSDL

REST

•Architecture

•Lightweight Payload• Postcard

•Human Readable Results

•Easy to work with, Brower-testable

•GET Method supports caching

•No Transactions

•Discovery• WADL?

USING REST

USING REST

Think of a REST API as another data source

Details 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 Header

• Make Call

• Deserialize Response

USING REST

Three basic options for consuming RESTful APIs

• 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 use

Downside

• 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 code

Downside

• Manual Discovery Process

• Implementation can be tedious

Tools

Tools for testing RESTful APIs

• Curl

• Eclipse Http4e

• Fiddler

• Your Browser (limited)

WADL

WADL

Web Application Discovery Language (WADL)

Created in 2005 by Marc Hadley of Sun Microsystems

Submitted to W3C on 8/31/2009

REST’s Answer to WSDL

Specification: https://wadl.dev.java.net/

What WADL Gets You

Reduced Errors in Discovery Opportunities for Code Generation

Spend more time building your application and less time implementing APIs

So Where Is It?

Currently in Submission to W3C API Providers are slow to adopt, so tool providers are slow to implement

There are projects underway to generate code from WADL, and at least one tool that helps in creating WADL

WADL DemoProject on code.google.com

Online Version: http://tomayac.de/rest-describe/latest/RestDescribe.html

Referenceshttp://en.wikipedia.org/wiki/Representational_State_Transfer

http://weblogs.java.net/blog/mhadley/archive/2005/05/introducing_wad.html

http://blog.tomayac.de/index.php?date=2007-05-23

RESTful Web Services – Richardson, Ruby – O’Reilly Press