© DZONE, INC.
|
DZONE.COM
CONTENTS
INTRODUCTION
The Representational State Transfer (REST) architectural
style is not a technology you can purchase or a library you
can add to your software development project. It is first and
foremost a worldview that elevates information into a first
class element of the architectures we build.
The ideas and terms we use to describe “RESTful” systems
were introduced and collated in Dr. Roy Fielding’s thesis,
“Architectural Styles and the Design of Network- based
Software Architectures”. This document is academic and
uses formal language, but remains accessible and provides
the basis for the practice.
The summary of the approach is that by making specific
architectural choices, we can elicit desirable properties
from the systems we deploy. The constraints detailed in this
architectural style are not intended to be used everywhere,
but they are widely applicable.
The concepts are well demonstrated in a reference
implementation we call the Web. Advocates of the REST style
are basically encouraging organizations to apply the same
principles within their boundaries as they do to external
facing customers with web pages.
THE BASICS
A RESTful service is exposed through a Uniform Resource
Locator (URL). This is a logical name that separates the
identity of the resource from what is accepted or returned.
The URL scheme is defined in RFC 1738.
A sample RESTful URL might be something like the following
fake API for a library:
http://fakelibrary.org/library
What is actually exposed is not necessarily an arbitrary
service, however, but an information resource representing
something of value to a consumer. The URL functions as a
handle for the resource, something that can be requested,
updated, or deleted.
This starting point would be published somewhere as
the way to begin interacting with the library’s REST
services. What is returned could be XML, JSON or—more
appropriately—a hypermedia format such as Atom or a
custom MIME type. The general guidance is to reuse existing
formats where possible, but there is a growing tolerance for
properly designed media types.
To request the resource, a client would issue a Hypertext
Transfer Protocol (HTTP) GET request to retrieve it. This
is what happens when you type a URL into a browser and
hit return, select a bookmark, or click through an anchor
reference link.
Get More Refcardz! Visit DZone.com/Refcardz
129
FOUNDATIONS OF RESTFUL ARCHITECTURE
For programmatic interaction with a RESTful API, any of a
dozen or moreclient sideAPIs or tools could be used. To use
the curl command line tool, you could type something like:
$ curl http://fakelibrary.org/library
This will return the default representation on the command
line. You may not want the information in this form,
however. Fortunately, HTTP has a mechanism by which you
can ask for information in a different form. By specifying an
“Accept” header in the request, if the server supports that
representation, it will return it. This is known as content
negotiation and is one ofthe moreunderused aspects of
HTTP. Again, using curl, this could be done with:
$ curl –H "Accept:application/json"
http://fakelibrary.org/library
This ability to ask for information in different forms is
possible because of the separation of the name of the
resource from its form. The ‘R’ in REST is ‘representation’, not
‘resource’. Keep this in mind and build systems that allow
clients to ask for information in the forms they want. We will
revisit this topic later.
Possible URLs for our fake library might include:
• http://fakelibrary.org/library - general
information about the library and the basis for
discovering links to search for specific books, DVDs, etc.
• http://fakelibrary.org/book - an “information
space” for books. Conceptually, it is a placeholder
for all possible books. Clearly, if it were resolved, we
would not want to return all possible books, but it
might perhaps return a way to discover books through
categories, keyword search, etc.
• http://fakelibrary.org/book/category/1234 -
within the information space for books, we might
FOUNDATIONS OF
RESTful Architecture
BY BRIAN SLETTEN
» The Basics
» What about SOAP?
» Richardson Maturity Model
» Verbs
» Response Codes... & more!
BROUGHT TO YOU IN PARTNERSHIP WITH
®
Delivering Security
Through Modern API
Architecture
Read now ›