unerstanding and using restful apis
DESCRIPTION
KeyLimeTie CTO Peter Morano provides an overview of using REST to architect applications. Complete with examples and resources.TRANSCRIPT
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