Академический Документы
Профессиональный Документы
Культура Документы
REST is simple.
Applying Enterprise-class
RESTful Capabilities
Security is Not. • Invoke Security Token Service
credential mapping or validation
• Ensure throttling and SLAs by
A Service Gateway will help you get REST service
there. Intel's SOA Expressway • Extend Enterprise audit and
provides a secure point of entry for compliance to WOA and REST
REST based services, a central • Detailed XML threat prevention
policy enforcement point where one and payload inspection
can delegate authentication and • Service virtualization, proxy,
and abstraction as a policy
authorization, and also effortless enforcement point
REST to SOAP mediation — without • REST API security and
having to write custom code. management
Visit our REST Solution page & tech tutorials to get started:
www.DynamicPerimeter.com
brought to you by...
#129
REST: Foundations of
CONTENTS INCLUDE:
Get More Refcardz! Visit refcardz.com
n
Introduction
The Basics
RESTful Architecture
n
n
What about SOAP?
n
Richardson Maturity Model
Verbs
By Brian Sletten
n
n
Response Codes and more...
happens when you type a URL into a browser and hit return,
INTRODUCTION
select a bookmark or click through an anchor reference link.
The Representational State Transfer (REST) architectural style For programmatic interaction with a RESTful API, any of a
is not a technology you can purchase or a library you can dozen or more client side APIs or tools could be used. To use
add to your software development project. It is a worldview the curl command line tool, you could type something like:
that elevates information into a first class element of the HHood> curl http://fakelibrary.org/library
architectures we build.
This will return the default representation on the command
The ideas and terms we use to describe “RESTful” systems line. You may not want the information in this form, however.
were introduced and collated in Dr. Roy Fielding’s thesis, Fortunately, HTTP has a mechanism by which you can
“Architectural Styles and the Design of Network-based ask for information in a different form. By specifying an
Software Architectures”. This document is academic and uses “Accept” header in the request, if the server supports that
formal language, but remains accessible and provides the basis representation, it will return it. This is known as content
for the practice. negotiation and is one of more underused aspects of HTTP.
www.dzone.com
The summary of the approach is that by making specific Again, using curl, this could be done with:
architectural choices, we can elicit desirable properties
HHood> curl –H “Accept:application/json” http://fakelibrary.org/
from the systems we deploy. The constraints detailed in this library
architectural style are not intended to be used everywhere but
This ability to ask for information in different forms is possible
they are widely applicable.
because of the separation of the name of the thing from
The concepts are well demonstrated in a reference its form. The ‘R’ in REST is ‘representation’, not ‘resource’.
implementation we call The Web. Advocates of the REST Keep this in mind and build systems that allow clients to ask
style are basically encouraging organizations to apply the for information in the forms they want. We will revisit this
same principles to coarsely granular information sources topic later.
within their firewalls as they do to external facing customers
Possible URLs for our fake library might include:
with web pages.
http://fakelibrary.org/library: general information about the
REST: Foundations of RESTful Architecture
THE BASICS library and the basis for discovering links to search for specific
books, DVDs, etc.
A Uniform Resource Locator (URL) is used to identify and http://fakelibrary.org/book: an “information space” for books.
expose a “RESTful service”. This is a logical name that Conceptually, it is a placeholder for all possible books.
separates the identity of an information resource from what is Clearly, if it were resolved, we would not want to return all
accepted or returned from the service when it is invoked. The
URL scheme is defined in RFC 1738.
Secure. Govern.
fake API for a library:
http://fakelibrary.org/library
possible books, but it might perhaps return a way to discover The confusion largely stems from the mistaken idea that REST
books through categories, keyword search, etc. “is about invoking Web services through URLs”. That has
about as much truth to it as the idea that “agile methodologies
http://fakelibrary.org/book/category/1234; within the
are about avoiding documentation.” Without a deeper
information space for books, we might imagine browsing them
understanding of the larger goals of an approach, it is easy to
based on particular categories (e.g. adult fiction, children’s
lose the intent of the practices.
books, gardening, etc.) It might make sense to use the Dewey
Decimal system for this, but we can also imagine custom REST is best used to manage systems by decoupling the
groupings as well. The point is that this “information space” information that is produced and consumed from the
is potentially infinite and driven by what kind of information technologies that do so. We can achieve the architectural
people will actually care about. properties of:
One of the key points about the GET request is that it should Note: Consider turning a query like this into an information
not modify anything on the server side. It is fundamentally resource itself. If you POST the definition into a query
a saferequest. This is one of the biggest mistakes made by information space, you can then issue GET requests to it, which
people new to REST. With RMM Level 1 systems, you often see can be cached. You can also share this link with others.
URLs such as: http://someserver/res/action=update?data=1234
PUT
Do not do this! Not only will RESTafarians mock you, but Many developers largely ignore the PUT verb because HTML
you will not build RESTful ecosystems that yield the desired forms do not support it. It serves an important purpose,
properties. The safety of a GET request allows it to be cached. however and is part of the full vision for RESTful systems.
GET requests are also intended to be idempotent. This When a client has a URL reference to an existing resource and
means that issuing a request more than once will have no wishes to update it, PUTing a representation to the URL serves
consequences. This is an important property in a distributed, as an overwrite action. This distinction allows a PUT request to
network-based infrastructure. If a client is interrupted while it be idempotent in a way that POST updates are not.
is making a GET request, it should be empowered to issue it
again because of this property. This is an enormously important If a client is in the process of issuing a PUT overwrite and it is
point. In a well-designed infrastructure, it does not matter interrupted, it can feel empowered to issue it again because
what the client is requesting from which application. There will an overwrite action can be reissued with no consequences; the
always be application-specific behavior, but the more we can client is attempting to control the state, so it can simply reissue
push into non-application-specific behavior, the more resilient the command.
and easier to maintain our systems will be.
Note: This protocol-level handling does not necessarily
POST preclude the need for higher (application-level) transactional
The situation gets a little less clear when we consider the intent handling, but again, it is an architecturally desirable property
of the POST and PUT verbs. Based on their definitions, both to bake in below the application level.
seem to be used to create or update a resource from the client
A PUT can also be used to create a resource if the client is able
to the server. They have distinct purposes, however.
to predict the resource’s identity. This is usually not the case
POST is used when the client cannot predict the identity of the as we discussed under the POST section, but if the client is in
resource it is requesting to be created. When we hire people, control of the server side information spaces, it is a reasonable
place orders, submit forms, etc., we cannot predict how the thing to allow. Publishing into a user’s weblog space is a typical
server will name these resources we are creating. This is why example of PUTing to a user-specified name.
we POST a representation of the resource to a handler (e.g.
servlet). The server will accept the input, validate it, verify the DELETE
user’s credentials, etc. Upon successful processing, the server The DELETE verb does not find wide use on the public Web
will return a 201 HTTP response code with a “Location” header (thankfully!), but for information spaces you control, it is a
indicating the location of the newly created resource. useful part of a resource’s lifecycle.
Note: Some people treat POST like a conversational GET on DELETE requests are intended to be idempotent, so you
should generally build resources that respond to DELETE The second collection of response codes indicates that the
requests by failing silently and returning a 200 even if it client should look elsewhere for the resource or information
has already been deleted. This may require extra state about it due to movement or some other situation.
management on the server to differentiate between DELETE
requests to things that no longer exist, versus requests to Code Description
things that never existed. 301 Moved Permanently. The requested resource is no longer located at the
specified URL. The new Location should be returned in the response
Some security policies may require you to return a 404 for non- header. Only GET or HEAD requests should redirect to the new location.
existent or deleted resources so DELETE requests do not leak The client should update its bookmark if possible.
information about the presence of resources. 302 Found. The requested resource has temporarily been found somewhere
else. The temporary Location should be returned in the response
There are three other verbs that are not as widely used but header. Only GET or HEAD requests should redirect to the new location.
provide value. The client need not update its bookmark as the resource may return to
this URL.
HEAD 303 See Other. This response code has been reinterpreted by the W3C
The HEAD verb is used to issue a request for a resource Technical Architecture Group (TAG) as a way of responding to a valid
request for a non-network addressable resource. This is an important
without actually retrieving it. It is a way for a client to check for
concept in the Semantic Web when we give URIs to people, concepts,
the existence of a resource and possibly discover metadata organizations, etc. There is a distinction between resources that can be
about it. found on the Web and those that cannot. Clients can tell this difference
if the get a 303 instead of 200. The redirected Location will be reflected
OPTIONS in the Location header in the response. It will contain a reference to
a document about the resource or perhaps some metadata about it.
The OPTIONS verb is also used to interrogate a server
This is not a universally popular decision but is currently the provided
about a resource by asking what other verbs are applicable to guidance.
the resource.
Table 2: Redirected Client Requests
PATCH
The third collection of response codes indicates that the
The newest of the verbs, PATCH was only officially adopted
client request was somehow invalid and will not be handled
as part of HTTP in early 2010. The goal is to provide a
successfully if reissued in the same condition. These
standardized way to express partial updates. The POST method
failures include potentially improperly formatted requests,
is basically unconstrained so it tends to defy constraint.
unauthorized requests, requests for resources that do not
A PATCH request in a standard format could allow an exist, etc.
interaction to be more explicit about the intent. There are Code Description
currently no standardized patch formats in wide RESTful use,
400 Bad Request. Generally the sign of a malformed or otherwise invalid
but they are likely to be designed for XML, HTML plain text and request.
other common formats.
401 Unauthorized. Without further authorization credentials, the client is not
allowed to issue the request. The inclusion of an “Authorization” header
RESPONSE CODES with valid credentials might still succeed.
403 Forbidden. The server is disallowing the request. Extra credentials will
not help.
HTTP response codes give us a rich dialogue between clients
404 Not Found. The server could not match the request to a known
and servers about the status of a request. Most people are resource.
only familiar with 200, 403, 404 and maybe 500 in a general
405 Method Not Allowed. The requested method (verb) is not allowed
sense, but there are many more useful codes to use. The tables for that resource. Response will indicate in an “Allow” header what is
presented here are not comprehensive, but cover many of allowed.
the most important codes you should consider using in a 406 Not Acceptable. The server cannot generate a representation
RESTful environment. compatible with what was asked for in the request “Accept” header.
410 Gone. The resource is explicitly no longer available and will not be in
The first collection of response codes indicates that the client the future.
request was well formed and processed. The specific action
411 Length Required. The server requires the client to specify a “Content-
taken is indicated by one of the following. Length” header indicating the size of the request. A resubmit with this
header might succeed.
Code Description 413 Entity Too Large. The request entity is too large for the server to process.
200 OK. The request has successfully executed. Response depends upon the 415 Unsupported Media Type. The client submitted a media type that is
verb invoked. incompatible for the specified resource.
201 Created. The request has successfully executed and a new resource
has been created in the process. The response body is either empty or Table 3: Invalid Client Requests
contains a representation revealing URIs for the resource created. The
The final collection of response codes indicates that the server
Location header in the response should point to the new URI as well.
was temporarily unable to handle the client request (which may
202 Accepted. The request was valid and has been accepted but has not yet
been processed. The response should include a URI to poll for status
still be invalid) and that it should reissue the command at some
updates on the request. This allows asynchronous REST requests. point in the future.
204 No Content. The request was successfully processed but the server did
not have any response. The client should not update its display.
There are many other implementations to investigate. For more This Week in REST:
information, please consult this list of known implementations: Site: http://thisweekinrest.wordpress.com
http://code.google.com/p/implementing-rest/wiki/ Mailing Lists
RESTFrameworks Rest-discuss: One of the most active and opinionated
Books mailing lists for discussion of REST topics. Many of the most
“RESTful Web Services” by Leonard Richardson and Sam Ruby, influential minds in the field congregate here to discuss both
2007. O’Reilly Media. fundamental and esoteric nuances of the architectural style.
This is best used as a read-only learning resource until you
“RESTful Web Services Cookbook” by SubbuAllamaraju, 2010.
have mastered the basics and need illumination on finer
O’Reilly Media.
points. Consider searching the archives before asking
“REST in Practice” by Jim Webber, SavasParastatidis and Ian introductory questions.
Robinson, 2010. O’Reilly Media.
Site: http://tech.groups.yahoo.com/group/rest-discuss/
“Restlet in Action” by Jerome Louvel and Thierry Boileau, 2011.
Manning Publications.
“Resource-Oriented Architectures : Building Webs of Data” by
Brian Sletten, 2011. Addison-Wesley.
#82
CONTENTS INCLUDE:
■
■
About Cloud Computing
Usage Scenarios Getting Started with
Aldon Cloud#64Computing
■
Underlying Concepts
Cost
by...
■
Upcoming Refcardz
youTechnologies ®
■
Data
t toTier
brough Comply.
borate.
Platform Management and more...
■
Chan
ge. Colla By Daniel Rubio
tion:
dz. com
tegra ternvasll
ABOUT CLOUD COMPUTING one time events. TEN TS
INC ■
HTML LUD E:
us Ind Anti-PPaat
Basics
Automated growthHTM
ref car
nuorn
■
Valid
ation one time events, cloud ML
connected to what is now deemed the ‘cloud’. Having the capability to support
RichFaces
Usef
Du
ti
■
ul M.
computing platforms alsoulfacilitate
Open the gradual growth curves
n an
Page Source
o
■
s
Vis it
C
faced by web applications. Tools
Core
By Key ■
Elem
Patte
E: has changed substantially in recent years, especially with ents Structur
LUD al Elem
TS INC ion the entrance of service providers like Amazon, Google and Large scale growth scenarios involvingents
specialized
and mor equipment
Integrat nge
rdz !
TEN
HTML
tinuous ry Cha Microsoft. e chang
es e... away by
(e.g. load balancers and clusters) are all but abstracted
out Con at Eve ns to isolat
ware space relying on a cloud computing platform’s technology.
CSS3
i-patter n
Re fca
e Work
ld Soft riptio
HTM
and Ant
Desc
These companies have a Privat itory
are in long deployedtrol repos webmana applications
ge
L BAS
tterns lop softw n-con to
ing and making them ICSplatforms support data
Control that adapt and scale
Deve
les toto large user
a versio bases,
ize merg
In addition, several cloud computing
ment
rn
ersion e... Patte it all fi minim le HTM
Manage s and mor e Work knowledgeable in amany
ine to
mainl aspects related tos multip
cloud computing. tier technologies that Lexceed the precedent set by Relational
space Comm and XHT
Build
re
Buil Repo
This Refcard active
will introduce are to you to clouddcomputing,within units with an
RATION etc. Some platforms ram support large grapRDBMS deployments. The src
dy Ha
softw
and Java s written in on of
riente
e ine loping hical
INTEG
task-o it attribute
softwar
Mainl emphasis onDeve es by all
S these
ines providers, so youComm can better understand
also rece JavaScri user interfac web develop and the rris
ADO.NET
reposit s that Pay only cieswhat you consume
tagge or Amazon’s cloud you cho platform
computing
the curr isome
heavily basedmoron fine. b></ ed insid
lained ) and anti the part solution duce nden For each (e.g. WAR es t
ent stan ose to writ more e imp a></ e
not lega each othe
exp x” al Depeapplication deployment ge nmen
orta b> is
be “fi ns are Web until t a
librarifew years ago
enviro was similar app
text
used
to to pro Minim packa nden t industry standard
that will softwaredardand virtualization
e HTM technology. nt, HTM
CI can ticular con i-patter they tend but can
rity all depe all targe
s will L or XHT arent. Reg the l, but r. Tags
etimes s. Ant tices,
to most phone services:
y Integ alizeplans with le that
late fialloted resources, ts with an and XHT simplify all help ML, und ardless
L VS
XHTM <a><
in a par hes som , Binar Centr
temp you prov b></
proces in the end bad prac lementing
nt nmen your
incurred costgeme whether e a single on MLaare of L
Creatsuchare resources were consumed orthenot.
t enviro Virtualization othe
based muchallows physical piece of hardware to
ide be erst HTM
approac ed with the cial, but,
cy Mana nt targe es to actually r web anding
a solid L has
essarily ed to imp of the
nden rties
Depe prope into differe chang
utilized by multiple operating simplerThis allows
function systems. coding.resources foundati job adm been arou
efi not nec compar
itting
associat to be ben
er
late Verifi te builds e comm commo Fortuna
alitytohas than on nd for
y are n Cloud computing asRun it’sremo
known etoday has changed this. expecte irably, that
befor etc.
Temp Build (e.g. bandwidth, nmemory, CPU) be movallocated they
exclusively totely HTM som
appear effects. The results whe
ually,
rm a
Privat y, contin Every elem used d. Earl job e time
ed The various s resourcesPerfo consumed by webperio applications
dicall (e.g. nt team
pag
individual operating entsinstances. ed to CSS
system to be, L Brow y HTM has expand . Whi
gration
opme
adverse unintend
d Build
common e (HTML because
ed far le it has don
sitory . ser
Build r to devel
web dev manufacture L had very
Repo
ous Inte
Stage
e bandwidth, memory, CPU) areIntegtallied
ration on a per-unit CI serve basis or XHT
produc ern. tinu e Build rm an ack from extensio .) All are limited more than e its
om
DZone, Inc.
ISBN-13: 978-1-936502-06-6
140 Preston Executive Dr. ISBN-10: 1-936502-06-2
Suite 100
50795
Cary, NC 27513