A Brief Introduction to REST
Posted by Stefan Tilkov on Dec 10, 2007
You may or may not be aware that there is debate going on about the “right” way
to implement heterogeneous application-to-application communication: While the
current mainstream clearly focuses on web services based on SOAP, WSDL and the
WS-* specification universe, a small, but very vocal minority claims there’s a
better way: REST, short for REpresentational State Transfer. In this article, I
will try to provide a pragmatic introduction to REST and RESTful HTTP
application integration without digressing into this debate. I will go into
more detail while explaining those aspects that, in my experience, cause the
most discussion when someone is exposed to this approach for the first time.
Key REST principles
Most introductions to REST start with the formal definition and background.
I’ll defer this for a while and provide a simplified, pragmatic definition:
REST is a set of principles that define how Web standards, such as HTTP and
URIs, are supposed to be used (which often differs quite a bit from what many
people actually do). The promise is that if you adhere to REST principles while
designing your application, you will end up with a system that exploits the
Web’s architecture to your benefit. In summary, the five key principles are:
• Give every “thing” an ID
• Link things together
• Use standard methods
• Resources with multiple representations
• Communicate statelessly
Let’s take a closer look at each of these principles.
Give every “thing” an ID
I’m using the term “thing” here instead of the formally correct “resource”
because this is such a simple principle that it shouldn’t be hidden behind
terminology. If you think about the systems that people build, there is usually
a set of key abstractions that merit being identified. Everything that should
be identifiable should obviously get an ID — on the Web, there is a unified
concept for IDs: The URI. URIs make up a global namespace, and using URIs to
identify your key resources means they get a unique, global ID.
The main benefit of a consistent naming scheme for things is that you don’t
have to come up with your own scheme — you can rely on one that has already
been defined, works pretty well on global scale and is understood by
practically anybody. If you consider an arbitrary high-level object within the
last application you built (assuming it wasn’t built in a RESTful way), it is
quite likely that there are many use cases where you would have profited from
this. If your application included a Customer abstraction, for instance, I’m
reasonably sure that users would have liked to be able to send a link to a
specific customer via email to a co-worker, create a bookmark for it in their
browser, or even write it down on a piece of paper. To drive home this point:
Imagine what an awfully horrid business decision it would be if an online store
such as Amazon.com did not identify every one of its products with a unique ID
(a URI).
When confronted with this idea, many people wonder whether this means they
should expose their database entries (or their IDs) directly — and are often
appalled by the mere idea, since years of object-oriented practice have told us
to hide the persistence aspects as an implementation detail. But this is not a
conflict at all: Usually, the things — the resources — that merit being
identified with a URI are far more abstract than a database entry. For example,
an Order resource might be composed of order items, an address and many other
aspects that you might not want to expose as individually identifiable
resources. Taking the idea of identifying everything that is worth being
identified further leads to the creation of resources that you usually don’t
see in a typical application design: A process or process step, a sale, a
negotiation, a request for a quote — these are all examples of “things” that
merit identification. This, in turn, can lead to the creation of more
persistent entities than in a non-RESTful design.
Related Vendor Content
Enterprise Integration Patterns: A Collection of 49 Flashcards
Shed Light into your Docker Containers
FREE Book: Docker Up & Running - Preview Edition (by O'Reilly)
Build Versus Buy: Customer Identity and User Management for Web and Mobile
Applications
Shipping Docker and Containers in Production - Download FREE eBook
Here are some examples of URIs you might come up with:
http://example.com/customers/1234
http://example.com/orders/2007/10/776654
http://example.com/products/4554
http://example.com/processes/salary-increase-234
As I’ve chosen to create human-readable URIs — a useful concept, even though
it’s not a pre-requisite for a RESTful design — it should be quite easy to
guess their meaning: They obviously identify individual “items”. But take a
look at these:
http://example.com/orders/2007/11
http://example.com/products?color=green
At first, these appear to be something different — after all, they are not
identifying a thing, but a collection of things (assuming the first URI
identifies all orders submitted in November 2007, and the second one the set of
green products). But these collections are actually things — resources —
themselves, and they definitely merit identification.
Note that the benefits of having a single, globally unified naming scheme apply
both to the usage of the Web in your browser and to machine-to-machine
communication.
To summarize the first principle: Use URIs to identify everything that merits
being identifiable, specifically, all of the “high-level” resources that your
application provides, whether they represent individual items, collections of
items, virtual and physical objects, or computation results.
Link things together
The next principle we’re going to look at has a formal description that is a
little intimidating: “Hypermedia as the engine of application state”, sometimes
abbreviated as HATEOAS. (Seriously — I’m not making this up.) At its core is
the concept of hypermedia, or in other words: the idea of links. Links are
something we’re all familiar with from HTML, but they are in no way restricted
to human consumption. Consider the following made-up XML fragment:
23
If you look at the product and customer links in this document, you can easily
imagine how an application that has retrieved it can “follow” the links to
retrieve more information. Of course, this would be the case if there were a
simple “id” attribute adhering to some application-specific naming scheme, too
— but only within the application’s context. The beauty of the link approach
using URIs is that the links can point to resources that are provided by a
different application, a different server, or even a different company on
another continent — because the naming scheme is a global standard, all of the
resources that make up the Web can be linked to each other.
There is an even more important aspect to the hypermedia principle — the
“state” part of the application. In short, the fact that the server (or service
provider, if you prefer) provides a set of links to the client (the service
consumer) enables the client to move the application from one state to the next
by following a link. We will look at the effects of this aspect in another
article soon; for the moment, just keep in mind that links are an extremely
useful way to make an application dynamic.
To summarize this principles: Use links to refer to identifiable things
(resources) wherever possible. Hyperlinking is what makes the Web the Web.
Use standard methods
There was an implicit assumption in the discussion of the first two principles:
that the consuming application can actually do something meaningful with the
URIs. If you see a URI written on the side of a bus, you can enter it into your
browser’s address field and hit return — but how does your browser know what to
do with the URI?
It knows what to do with it because every resource supports the same interface,
the same set of methods (or operations, if you prefer). HTTP calls these verbs,
and in addition to the two everyone knows (GET and POST), the set of standard
methods includes PUT, DELETE, HEAD and OPTIONS. The meaning of these methods is
defined in the HTTP specification, along with some guarantees about their
behavior. If you are an OO developer, you can imagine that every resource in a
RESTful HTTP scenario extends a class like this (in some Java/C#-style
pseudo-syntax and concentrating on the key methods):
class Resource {
Resource(URI u);
Response get();
Response post(Request r);
Response put(Request r);
Response delete();
}
Because the same interface is used for every resource, you can rely on being
able to retrieve a representation — i.e., some rendering of it — using GET.
Because GET’s semantics are defined in the specification, you can be sure that
you have no obligations when you call it — this is why the method is called
“safe”. GET supports very efficient and sophisticated caching, so in many
cases, you don’t even have to send a request to the server. You can also be
sure that a GET is idempotent — if you issue a GET request and don’t get a
result, you might not know whether your request never reached its destination
or the response got lost on its way back to you. The idempotence guarantee
means you can simply issue the request again. Idempotence is also guaranteed
for PUT (which basically means “update this resource with this data, or create
it at this URI if it’s not there already”) and for DELETE (which you can simply
try again and again until you get a result — deleting something that’s not
there is not a problem). POST, which usually means “create a new resource”, can
also be used to invoke arbitrary processing and thus is neither safe nor
idempotent.
If you expose your application’s functionality (or service’s functionality, if
you prefer) in a RESTful way, this principle and its restrictions apply to you
as well. This is hard to accept if you’re used to a different design approach —
after all, you’re quite likely convinced that your application has much more
logic than what is expressible with a handful operations. Let me spend some
time trying to convince you that this is not the case.
Consider the following example of a simple procurement scenario:
Sample Scenario
You can see that there are two services defined here (without implying any
particular implementation technology). The interface to these services is
specific to the task — it’s an OrderManagement and CustomerManagement service
we are talking about. If a client wants to consume these services, it needs to
be coded against this particular interface — there is no way to use a client
that was built before these interfaces were specified to meaningfully interact
with them. The interfaces define the services’ application protocol.
In a RESTful HTTP approach, you would have to get by with the generic interface
that makes up the HTTP application protocol. You might come up with something
like this:
Sample Scenario, done RESTfully
You can see that what have been specific operations of a service have been
mapped to the standard HTTP methods — and to disambiguate, I have created a
whole universe of new resources. “That’s cheating!”, I hear you cry. No - it’s
not. A GET on a URI that identifies a customer is just as meaningful as a
getCustomerDetails operation. Some people have used a triangle to visualize
this:
Knobs one can turn
Imagine the three vertices as knobs that you can turn. You can see that in the
first approach, you have many operations and many kinds of data and a fixed
number of “instances” (essentially, as many as you have services). In the
second, you have a fixed number of operations, many kinds of data and many
objects to invoke those fixed methods upon. The point of this is to illustrate
that you can basically express anything you like with both approaches.
Why is this important? Essentially, it makes your application part of the Web —
its contribution to what has turned the Web into the most successful
application of the Internet is proportional to the number of resources it adds
to it. In a RESTful approach, an application might add a few million customer
URIs to the Web; if it’s designed the same way applications have been designed
in CORBA times, its contribution usually is a single “endpoint” — comparable to
a very small door that provides entry to a universe of resource only for those
who have the key.
The uniform interface also enables every component that understands the HTTP
application protocol to interact with your application. Examples of components
that benefit from this are generic clients such as curl and wget, proxies,
caches, HTTP servers, gateways, even Google/Yahoo!/MSN, and many more.
To summarize: For clients to be able to interact with your resources, they
should implement the default application protocol (HTTP) correctly, i.e. make
use of the standard methods GET, PUT, POST, DELETE.
Resources with multiple representations
We’ve ignored a slight complication so far: how does a client know how to deal
with the data it retrieves, e.g. as a result of a GET or POST request? The
approach taken by HTTP is to allow for a separation of concerns between
handling the data and invoking operations. In other words, a client that knows
how to handle a particular data format can interact with all resources that can
provide a representation in this format. Let’s illustrate this with an example
again. Using HTTP content negotiation, a client can ask for a representation in
a particular format:
GET /customers/1234 HTTP/1.1
Host: example.com
Accept: application/vnd.mycompany.customer+xml
The result might be some company-specific XML format that represents customer
information. If the client sends a different request, e.g. one like this:
GET /customers/1234 HTTP/1.1
Host: example.com
Accept: text/x-vcard
The result could be the customer address in VCard format. (I have not shown the
responses, which would contain metadata about the type of data in the HTTP
Content-type header.) This illustrates why ideally, the representations of a
resource should be in standard formats — if a client “knows” both the HTTP
application protocol and a set of data formats, it can interact with any
RESTful HTTP application in the world in a very meaningful way. Unfortunately,
we don’t have standard formats for everything, but you can probably imagine how
one could create a smaller ecosystem within a company or a set of collaborating
partners by relying on standard formats. Of course all of this does not only
apply to the data sent from the server to the client, but also for the reverse
direction — a server that can consume data in specific formats does not care
about the particular type of client, provided it follows the application
protocol.
There is another significant benefit of having multiple representations of a
resource in practice: If you provide both an HTML and an XML representation of
your resources, they are consumable not only by your application, but also by
every standard Web browser — in other words, information in your application
becomes available to everyone who knows how to use the Web.
There is another way to exploit this: You can turn your application’s Web UI
into its Web API — after all, API design is often driven by the idea that
everything that can be done via the UI should also be doable via the API.
Conflating the two tasks into one is an amazingly useful way to get a better
Web interface for both humans and other applications.
Summary: Provide multiple representations of resources for different needs.
Communicate statelessly
The last principle I want to address is stateless communication. First of all,
it’s important to stress that although REST includes the idea of statelessness,
this does not mean that an application that exposes its functionally cannot
have state — in fact, this would render the whole approach pretty useless in
most scenarios. REST mandates that state be either turned into resource state,
or kept on the client. In other words, a server should not have to retain some
sort of communication state for any of the clients it communicates with beyond
a single request. The most obvious reason for this is scalability — the number
of clients interacting would seriously impact the server’s footprint if it had
to keep client state. (Note that this usually requires some re-design — you
can’t simply stick a URI to some session state and call it RESTful.)
But there are other aspects that might be much more important: The
statelessness constraint isolates the client against changes on the server as
it is not dependent on talking to the same server in two consecutive requests.
A client could receive a document containing links from the server, and while
it does some processing, the server could be shut down, its hard disk could be
ripped out and be replaced, the software could be updated and restarted — and
if the client follows one of the links it has received from the server, it
won’t notice.
REST in theory
I have a confession to make: What I explained is not really REST, and I might
get flamed for simplifying things a little too much. But I wanted to start
things a little differently than usual, so I did not provide the formal
background and history of REST in the beginning. Let me try to address this, if
somewhat briefly.
First of all, I’ve avoided taking great care to separate REST from HTTP itself
and the use of HTTP in a RESTful way. To understand the relationship between
these different aspects, we have to take a look at the history of REST.
The term REST was defined by Roy T. Fielding in his PhD thesis (you might
actually want to follow that link — it’s quite readable, for a dissertation at
least). Roy had been one of the primary designer of many essential Web
protocols, including HTTP and URIs, and he formalized a lot of the ideas behind
them in the document. (The dissertation is considered “the REST bible”, and
rightfully so — after all, the author invented the term, so by definition,
anything he wrote about it must be considered authorative.) In the
dissertation, Roy first defines a methodology to talk about architectural
styles — high-level, abstract patterns that express the core ideas behind an
architectural approach. Each architectural style comes with a set of
constraints that define it. Examples of architectural styles include the “null
style” (which has no constrains at all), pipe and filter, client/server,
distributed objects and — you guessed it — REST.
If all of this sounds quite abstract to you, you are right — REST in itself is
a high-level style that could be implemented using many different technologies,
and instantiated using different values for its abstract properties. For
example, REST includes the concepts of resources and a uniform interface — i.e.
the idea that every resource should respond to the same methods. But REST
doesn’t say which methods these should be, or how many of them there should be.
One “incarnation” of the REST style is HTTP (and a set of related set of
standards, such as URIs), or slightly more abstractly: the Web’s architecture
itself. To continue the example from above, HTTP “instantiates” the REST
uniform interface with a particular one, consisting of the HTTP verbs. As
Fielding defined the REST style after the Web — or at least, most of it — was
already “done”, one might argue whether it’s a 100% match. But in any case, the
Web, HTTP and URIs are the only major, certainly the only relevant instance of
the REST style as a whole. And as Roy Fielding is both the author of the REST
dissertation and has been a strong influence on the Web architecture’s design,
this should not come as a surprise.
Finally, I’ve used the term “RESTful HTTP” from time to time, for a simple
reason: Many applications that use HTTP don’t follow the principles of REST —
and with some justification, one can say that using HTTP without following the
REST principles is equal to abusing HTTP. Of course this sounds a little
zealous — and in fact there are often reasons why one would violate a REST
constraint, simply because every constraint induces some trade-off that might
not be acceptable in a particular situation. But often, REST constraints are
violated due to a simple lack of understanding of their benefits. To provide
one particularly nasty example: the use of HTTP GET to invoke operations such
as deleting an object violates REST’s safety constraint and plain common sense
(the client cannot be held accountable, which is probably not what the server
developer intended). But more on this, and other notable abuses, in a follow-up
article.
Summary
In this article, I have attempted to provide a quick introduction into the
concepts behind REST, the architecture of the Web. A RESTful HTTP approach to
exposing functionality is different from RPC, Distributed Objects, and Web
services; it takes some mind shift to really understand this difference. Being
aware about REST principles is beneficial whether you are building applications
that expose a Web UI only or want to turn your application API into a good Web
citizen.
Stefan Tilkov is the lead editor of InfoQ’s SOA community and co-founder,
principal consultant and lead RESTafarian of Germany/Switzerland-based innoQ.
------
Love the analogy by `Peter Lacey'
In a RESTful approach, an application might add a few million customer URIs
to the Web; if it’s designed the same way applications have been designed
in CORBA times, it’s contribution usually is a single “endpoint” —
comparable to a very small door that provides entry to a universe of
resource only for those who have the key.
Brilliant.
• Reply
• Back to top
REST on .NET? by `Ole Friis'
At the project I'm currently working on, it would be really nice to have a REST
interface instead of the SOAP interface we're currently going for. The reason
we're going for SOAP is that the project is done in .NET 2.0, and the .NET
framework has excellent support for SOAP.
However, I have not been able to find good .NET REST frameworks. Microsoft is
doing Astoria, but that's a "let's publicise your database through the Web"
thing, and besides that it requires WCF and thus .NET 3.
Does anybody know of any (preferably open-source) REST frameworks for .NET that
are worth checking out?
• Reply
• Back to top
RESTful with many parameters? by `Tom Dyer'
How would you request a resource that was identified by a large set of
parameters?
For example, I want a list of all the dependent/required products for a given
set of products.
URI is /required_products/{43,555, .... very large set of product ids} And the
resource identified is the list of required products for this set of products
ids.
Seems like its GET but are there too many parameters needed to identify the
resource?
Maybe a POST but a post is not safe, indempotent and is typically used to
create a new resource, which the list of dependencies is not.
Perhaps a POST. But a POST is not "safe", it can have side effects, and is
typically used for a resource update or for creating a new resource associated
with the URI.
thanks,
• Reply
• Back to top
very nice by `Nikita Ivanov'
One of the clearest REST articles I've read in a while... Thanks!
Nikita Ivanov.
GridGain - Grid Computing Made Simple
• Reply
• Back to top
Re: RESTful with many parameters? by `Rafael de F. Ferreira'
I don't see why not use GET. HTTP doesn't prescribe an upper bound on the size
of the URI.
• Reply
• Back to top
Re: RESTful with many parameters? by `Tom Dyer'
I dunno, that kind of smells bad. I mean isn't the resource identifier, set of
product ids here, just going to get too large at some point?
Wonder if the set of product id's aren't a resource that can be created, via
POST, then it's identifier/URI can be used to GET the collection of dependent
products.
• Reply
• Back to top
Re: RESTful with many parameters? by `lipman li'
Unless you call get the very long URI within browser(browser does have the
length limitation), it shall not be any problem to interact between
applications provided the applications do not have length limitation on the get
URL length. HTTP itself seems no length limitation.
• Reply
• Back to top
Re: RESTful with many parameters? by `Kirstan Vandersluis'
I agree HTTP itself does not impose a limit, but I have experienced GET size
limitations on a number of projects within browsers, typcially accessing
XML-based resources with attached XSL stylesheets. If your calling clients are
only other applications, it would seem that this would work. But another
caution is that intermediaries might impose size restrictions (see for example:
classicasp.aspfaq.com/forms/what-is-the-limit-o...).
I'd have to agree with Tom Dyer that the approach of stuffing an arbitrarily
large list into the query string seems awkward. I think this situation fits
Stefan's "exception criteria" from his article:
"...there are often reasons why one would violate a REST constraint, simply
because every constraint induces some trade-off that might not be acceptable in
a particular situation"
I certainly don't claim to be a REST expert, but in my opinion, I'd say a POST
would be a better approach in this case.
• Reply
• Back to top
Representations by `Jim Standley'
Is an editor a representation?
Is it ok to put representation on the URL?
I have done this recently:
/Repo/Element/101 <- returns HTML
/Repo/Element/101?json <- returns JSON
/Repo/Element/101?edit <- returns an edit page
• Reply
• Back to top
Re: RESTful with many parameters? by `Tom Dyer'
I tend to agree with Kirstan and think I'd use a POST and not be so tied to the
REST uniform interface for this case. Good point about possible intermediary
limitations.
Also, I probably wouldn't get the caching benefits of GET because the same URI
from this large set of URI's wouldn't be accessed that often. The resource
would mostly likely not be a good caching canidate.
This is probably taking this to the absurd but can one use an executable
artifact,( proc, code block, SQL select,...), as part of URI. The result of
executing the block on the Resource server would be used to identify the
resource.
• Reply
• Back to top
Re: Representations by `Tom Dyer'
Yes, it's ok to put the representation on the URL. This is what Rails does and
is suggested by the O'Reilly REST Web Services book.
"/Repo/Element/101?edit <- returns an edit page" is similar to the URI used in
Rails for a form that will be filled in to update a resource.
Would be /Repo/Element/101/edit in rails.
• Reply
• Back to top
Re: REST on .NET? by `Stefan Tilkov'
Ole, you might want to check out these postings:
www.infoq.com/news/2007/05/wcf-web-programming-...
and
www.infoq.com/news/2007/10/mindtouch-dream
HTH,
Stefan
• Reply
• Back to top
Re: RESTful with many parameters? by `Stephan Schlöpke'
I think a better way to use this would be to have a sort of "search" or "query"
you create. You could do a post on some URI like ./query/product_dep which
would create a query resource. Now you "add" products to the query either by
sending a product uri list with the initial post or by calling post on ./query/
product_dep/{id}. With every post to the query resource the get on the query
resource would change.
It is very similar with searching something with multiple parameters. In such a
case it would be much easier to create a search resource and once created do a
get on the created resource. And when done just send a delete to the created
query resource.
There are multiple ways to solve this. However I think doing a GET on an URI
and building the URI like ./something/{10,20,40 ...} on the client seems not
right. It would require the client to have a detail knowledge of building the
URIs while normaly the client should only follow links provided by the service.
Very nice articel stephan btw :-)
• Reply
• Back to top
c# Interface analogy by `Maximilian Schulz'
Although it is a different analogy than Peter was referring to, I love the one
about c# Interfaces. We have some hardcore c# guys here who I try to convince
to give REST based services a try. And the Interface analogy is probably
perfect to describe how it can be understood. I will give it a try next week
during our end-of-year-team-meeting-and-evaluation. Anyways, REST is not that
new to me, but I cannot wait to read the next part ;)
• Reply
• Back to top
Re: RESTful with many parameters? by `Kirstan Vandersluis'
I think that creating and managing a "query set" object on the server side
violates another RESTful criteria - operations should be stateless. I suppose
you could take the view that a "query set" itself is an application object,
with a URI as you mention. Then REST operations like PUT, GET, DELETE would
make sense to manage the query set. Still seems a bit awkward though, for
performance reasons if nothing else. If I'm querying for 100 items, that's 100
PUTs to my query set before I invoke the query. There should instead be an
operation to send a query in one operation, and I think POST is just fine to do
this.
• Reply
• Back to top
Re: RESTful with many parameters? by `Stephan Schlöpke'
Actually there is no reason to PUT a list of query items in mutliple PUTs. If
for instance you have 100 items to query why not just do a put to create a
query resource sending all 100 items at once? And I wouldn't say it violates
any RESTful criteria. Actually it is stateless since the state is persistent in
the resource (in this case the query resource). And to my understanding that is
the idea. Instead of using session states put the state into the Resource. And
I see not really a difference to the POST. A PUT creates a resource and returns
the link to the created resource. The resource created is the result of the
query. And optionally PUT can return not only the new location but the content
as well. So with one PUT you can get the result. Difference to POST is that you
do not need to remember the result since with the location beeing changed to
the resource you can just refresh the location and receive your result again
(Or you can link it unless you delete the query right after you used it).
Mostly you can do that with POST too but normaly you POST to a resource to
update it. So the POST way would be a violation of the uniform interface
definition I think. But I don't think the PUT/GET/DELETE is a violation.
• Reply
• Back to top
Resource graph traversal is not the same as state transition by `Ganesh Prasad'
Stefan, great article. I understand and greatly respect the REST view of the
world. However, I have found in my discussions with RESTafarians that there are
some aspects that tend to be confusing, especially the terminology that tends
to be used around the HATEOAS concept.
You said:
> There is an even more important aspect to the hypermedia principle — the
“state” part of the application. In short, the fact that the server (or service
provider, if you prefer) provides a set of links to the client (the service
consumer) enables the client *to move the application from one state to the
next by following a link*.
When you say the client "moves the application from one state to the next", I
understand that to mean that updates are taking place. But if the client is
merely traversing links (using a sequence of GETs, for example), then the
application's state has not changed at all. What has changed is the client's
view or representation of the application. The client has merely changed its
perspective of the application's state and is looking at it from a different
"angle", so to speak. In other words, the client is traversing the resource
graph, which is a hyperlinked set of URIs representing resources.
We need to make a clear distinction between State Transitions (which most
people would expect to only occur on updates), and mere link traversals, which
change the client's view (representation) of the application but not its state.
If the HATEAOS model means link traversal when it talks about state
transitions, then we really need to clean up the terminology, because it
needlessly confuses non-RESTafarians.
Regards,
Ganesh
• Reply
• Back to top
Re: Resource graph traversal is not the same as state transition by `Stephan
Schlöpke'
You sure can do a state transition with resource traversal. For example you
have a resource which is in the edit state and you edit it at someuri/resource/
id now you get the link to someuri/resource/id?state=finish. When you follow
that link the state changes on the resource is no longer editable. The state
change you can call multiple times without ever returning with a different
result. Now you wouldn't be given an edit link anymore and calling the old edit
link to edit the resource would result in an illegal state result.
I think that this is a real state transition and I would say that it conforms
to REST.
• Reply
• Back to top
Re: RESTful with many parameters? by `Kirstan Vandersluis'
That seems viable, Stephan, to use a PUT as you describe, to load the entire
query with one call instead of the 100 calls I previously stated. But I am
still bothered a bit by state. You mention "The resource created is the result
of the query". Initially, I thought we were discussing building up a query,
storing the query as a resource (using PUT), then being able to reference that
resource to invoke the query. Either way, whether you store the query or store
its results, you have created session-specific data, and will need to consider
its management. Do you rely on the client to DELETE it? What if they don't?
Does it get removed with a session timeout? This session data is one thing REST
attempts to avoid by recommending stateless interactions. So if we have to bend
the rules and go outside the normal REST mode of operation, I would still opt
to pass these large queries through a POST.
• Reply
• Back to top
Re: RESTful with many parameters? by `Stephan Schlöpke'
I would in most cases only store the query in a database. I did this in a
project recently. We store the query in the database and the client also
submits a time to life. So if the client does not delete the query it gets
removed later. That is the state stored in the resource rather than having a
session management. A batch which for example checks once an hour removes all
entries in the database which are outdated. Idially the client sends a DELETE
when the result resource is no longer needed.
It is like in real life. I have a guy in my office called Archie. He is
responsible to gain documents from the libray whenever someone needs it. Once I
have a request for a couple of documents I hand him a list what to get. Now I
can just wait until he got everything in order to take it with me. Or I go back
into my office waiting for an email that he has gathered all my documents for
me to pick up.
In a service designed like that I create a list which is my query request. I do
a PUT to archie so he has the newly created list. The receipt I get is an URI
where I can get my documents once they are collected. In the normal case they
are instantly available so I just do a GET on the resource and have my result.
In various situations a backend needs more time to gather the documents
together which may take a couple of minutes. This gives me as a client the
option to inform the user that his request is beeing processed. Once the
request is processed the user can see the result. Or if it is a real long
request a mail is send to the user with the URI link where to get the result.
Since Archie wants his documents back he keeps the list until I am done with
the documents. Once I am done I return the documents and get the list back or
the list gets destroyed. This is where the client puts the DELETE to the
result. Once he or she is done with it.
The good thing in it is that if you execute the query and stores the result it
is totally independend from someone deleting or adding entries to the database.
Those the result I see dosnt change while I am working with it. This can be of
benefit especially when you do a search. If you send the link result to another
person he or she can open it and the 4th entry is the same you saw. In some
cases it might be better to store the query and the first get removes it. This
however is not REST conform I think since the GET I can only execute once.
Executing a DELETE with the option of a timeout and a clean up task is I think
the best way to go. In such a case the client has the chance to work with the
result resource as long as he wants without having to store it. Also this way
it is easy to cache such a resource while with POST you cannot cache the
resource in a proxy since the proxy dosn't know in what relationship the posted
content to the result is.
• Reply
• Back to top
Re: Resource graph traversal is not the same as state transition by `Stefan
Tilkov'
Ganesh, you write
When you say the client "moves the application from one state to the next",
I understand that to mean that updates are taking place. But if the client
is merely traversing links (using a sequence of GETs, for example), then
the application's state has not changed at all.
There is resource state and application state, and I agree the traversal of a
link by the client via GET does not change the resource state. But it changes
the application state, as the client is now "looking at" or "holding on to" a
different representation which includes different links than the one before.
Application state is thus kept on the client (which means the server doesn't
care about it). But the representations sent from the server to the client
"drives" it because they contain or do not contain links to specific other
resources.
"Hypermedia as the engine of application state" is both the least understood
and the most powerful aspect of REST, which is why we have an article just
about this coming up soon.
• Reply
• Back to top
What when REST semantics are not enough? by `Gael Fraiteur'
It seems like REST semantics are identical to CRUD ones: Create, Update,
Delete. It forces each resource to have a very simple state diagram: a start
node with a CREATE transition, then a unique normal node with an UPDATE
transition, looping back to itself, and a DELETE transition, going to the
terminal node. This is a pretty simplistic representation of the state of a
resource.
What is we want to have a richer state diagram? Take the example of an order,
how to represent the transition from the state "booked" to "shipped" (this is a
parameterless transition). And how to represent the transition to the state
"cancelled", when we want to add the reason cancellation (transition with one
parameter).
Object-oriented methologies have learned us how to deal with these situations
using procedures/methods, but what would be the right approach using REST?
• Reply
• Back to top
Excellent by `Sadek Drobi'
Great article Stefan, waiting for the next!
• Reply
• Back to top
Re: RESTful with many parameters? by `Ally Kendall'
I would use indirection. I.e. I would give it a shorter name, such as a hash of
the parameters.
• Reply
• Back to top
Re: What when REST semantics are not enough? by `Ally Kendall'
These are updates, which are POSTs. In OO terms, the method specifier is always
a parameter of a POST.
• Reply
• Back to top
Re: What when REST semantics are not enough? by `Stefan Tilkov'
There are multiple options: one is to PUT a new state to the resource,
effectively changing its internal e.g. from booked to shipped. Another way is
to do a logical move of the resource from one collection (of booked orders) to
another (of shipped orders). A third way is to represent the state change as a
resource in itself, e.g. by POSTing it to the order where it becomes a
sub-resource. This way, you have a history of changes.
The mapping to CRUD is not 1:1 -- a POST can create new resources, or simply
process something and return a result. In case a POST is used to create a new
resource, the server chooses the URI. A PUT can be used when the URI of the
resource one wants to affect is known -- it will either create or update a
resource there.
• Reply
• Back to top
Re: Love the analogy by `Mike Glendinning'
Of course in the real world, where confidentiality and privacy of customer
information is important, implementing a "small door with a key" is often a
good idea! Just ask the UK government after their recent loss of personal
banking details for 25 million citizens :-)
In fact this is one of the interesting tensions in the design of web-based
hypermedia applications: The more we make data accessible through URIs and
hyperlinks, the harder it becomes to secure and control access. This problem is
exacerbated by the crude security framework of HTTP.
In the world of "enterprise applications" the norm has been for years to design
systems that strictly control access to data. This is in line with the design
and operation of our organisations, but contrasts markedly with the web where
the goal has always been to *provide* access to data. It has also lead to a
whole new industry for enterprise data warehousing and business intelligence
solutions that "unlock" hidden data.
If REST is to "take over" for enterprise applications, I suggest it's going to
have to address issues of data security much more seriously. The long term
effects on our enterprise architecture might be quite interesting, nonetheless.
• Reply
• Back to top
Re: Resource graph traversal is not the same as state transition by `Ganesh
Prasad'
Stefan Tilkov said:
There is resource state and application state [...]
Ah, that explains everything! In my terminology, there's "client state" and
"application state". You call them "application state" and "resource state".
Fair enough!
This ties in neatly with our model SOFEA (Service-Oriented Front-End
Architecture), where client state is managed on the client, and a controller on
the client side interacts with services (either SOAP or REST) to drive what we
call "Presentation Flow". Obviously, client state and Presentation Flow are
constrained by the representations that the service tier exposes.
I think it's important to clarify that SOAP-based Web Services also expose
*representations* of behaviour, because these do not simply mirror methods on
Domain Objects. Unlike with REST-based "services", client state is not directly
constrained by SOAP-based web services. Because of its nature as a
verb-oriented view of a domain (rather than a noun-oriented view that is REST),
either a whole process has to be encapsulated in a single operation
(implemented by WS-BPEL) for the client to consume, or the client has to define
a bespoke process using the set of services available. This is not necessarily
a disadvantage. It's just a different model.
Regards,
Ganesh
• Reply
• Back to top
Architecture of resources ? by `Vladimir Vacula'
Great article Stefan. I was thinking about your example with resources. You
presented resources :
- "/orders" and "/orders/{id}"
- "/customers" and "/customers/{id}"
- "/customers/{id}/orders"
what if i don't want to categorize object in URI-name of resources. What if
"id" means just a document without identification, if document is an order or
customer card?
Let's say i have resources :
- "/document/{id}" (which implement GET of details and POST of new documents)
- "/search" (which returns list and implement POST of restricting conditions
i.e. "category:customer" or more complex "category:customer, category_id:123,
relation:orders" )
Is it better to use categories in URI of resources (like "/orders") instead of
creating general resources (like "/search")? Is there any recommendation which
way is better and why? And finally, what if "/orders" returns really huge list?
In "/search" i could implement condition i.e. "last:10", "max_date:2006-12-31".
How to handle this issue in case i use resource "/orders" ?
Thanks
• Reply
• Back to top
Re: Architecture of resources ? by `Stefan Tilkov'
Hi Vladimir,
First of all, the characters that make up a URI are much less important than
one may think. But anway, I prefer to give resources meaningful names -- but
this is just a design decision. Your document/{id} example would mean that a
POST to it would be handled the same way, regardless of whether it's an order
or customer, unless you switch on the content type. If handling both similarly
-- e.g. if you just want to store a new document without looking at its
contents -- is what you want, this seems perfectly fine.
I suggest to implement searches as GETs, not POSTs -- it's useful to be able to
link to a search result, and it's a meaningful resource in itself -- "the list
of all customers named Smith" qualifies as a resource from my POV.
Regarding the large lists, one way is to redirect a request to /orders to /
orders?offset=0&count=10 and include a link to /orders?offset=10&count=10 --
i.e., the indivual pages become resources in themselves.
HTH,
Stefan
• Reply
• Back to top
Re: Love the analogy by `Felipe Nascimento'
Great article.
Do you suggest any material about REST security we can take a look at? If
application does not hold state, how to check if some client application has
the authority to access one resource? Should the client application pass in the
credentials in every request? Should the RESTful application has a security
service that would return a session ID that would be used by the client
application in every subsequent requests?
Tks
Felipe
• Reply
• Back to top
Re: Love the analogy by `Stefan Tilkov'
Thanks Felipe. Yes, both sending the credentials with every request (the way
HTTP Basic Auth does things) and sending a security token (similar to Google's
WebAuth) are fine. I will take up REST security as another topic to cover - not
necessarily by myself.
• Reply
• Back to top
Re: RESTful with many parameters? by `Torben Wölm'
You could also use custom http-headers for your many parameters...
• Reply
• Back to top
Understanding the Difference! by `William Martinez'
A RESTful HTTP approach to exposing functionality is different from RPC,
Distributed Objects, and Web services; it takes some mind shift to really
understand this difference
Stefan, totally agree with your claim. Most of the discussion I've had in the
past relates to the confusion of all those four things. For some, Web Services
are just a way to distribute object (thus a WS is an exposed object!), some
others cannot imaging WS as a messaging thing: it is just an exposed method
(RPC). Even more, some see on REST a simpler WS, which is not. I mean REST is
much more that just WS, and WS can be implemented using REST philosophy. In
fact, WS architecture's resource view is totally compatible with REST.
But to understand this, you need a "mind shift", totally true.
• Reply
• Back to top
So IOW, this applies only to web projects. What about Windows projects? by
`Parimal Jisaheb'
So IOW, this applies only to web projects. What about Windows projects?
• Reply
• Back to top
Re: So IOW, this applies only to web projects. What about Windows projects? by
`Stefan Tilkov'
If I understand your question correctly: no, this does not only apply to
projects that use an HTML UI - you could have your rich client communicate with
your server using HTTP according to REST principles.
• Reply
• Back to top
Thanks by `Yuen Chi Lian'
This article has definitely helped me to form a clearer picture about REST and
its fundamental.
Cheers,
yc
• Reply
• Back to top
Re: Architecture of resources ? by `Mike S'
A bit off topic but this post reminded me of one project which might be of
interest to the poster.
On topic though totally agree with Stefan's response. Search should be exposed
as GET-able URI which effectively creates unlimited list of resources which are
search results. Just a slight addition to the pagination solution: I think it
is better be done the same way content negotiation is, that is GET /orders
would return same representation as /orders?offset=0&count=10 mentioning the
latter as Location header so that the client can cache the result against the
proper key. Interestingly the spec talks about Location header as the target
for redirection :).
• Reply
• Back to top
Re: What when REST semantics are not enough? by `Mike Schinkel'
Actually, in a RESTful design PUT is used for UPDATE (only) or INSERT (when the
client determines the resource URI) and POST can be used to INSERT or various
other processes.
• Reply
• Back to top
Re: RESTful with many parameters? by `Mike Schinkel'
POST is part of REST's uniform interface. For HTTP, that uniform interface is
generally considered to be GET, PUT, POST, DELETE, and HEAD although it can
include a few other like PATCH.
And since REST is an architecture style it could be used with a different
request/response protocol and with a different uniform methods although that's
just a point to clarify the though process as few people are using REST outside
HTTP.
• Reply
• Back to top
Re: Love the analogy by `Mike Schinkel'
The type of security concerns you mention are a red-herring. RESTful apps can
be fulled secured with SSL on top of HTTP security. Or do you view SSL as not
being sufficient and if so, why?
• Reply
• Back to top
Re: Resource graph traversal is not the same as state transition by `Mike
Schinkel'
Actually, the term "representation" is a defined term in the context of REST as
per the W3C's Architecture of the World Wide Web, Volume One as opposed to your
colloquial use of the term related to SOAP. And the fact that the client has an
effectively infinite potential number of operations to know and understand in
SOAP as opposed to the tight contrained number of operations is one of the key
advantages of REST.
Consider REST like the physical compatibility of the plug on your computer's
power cord and the electrical outlet where your computer gets its power. REST's
constraint on verbs is like the plug/outlet's physical compatibility contraint.
Conversely imagine having every power cord had a different type of plug; that
is SOAP and all its operations! Actually if you travel a lot internationally,
you already know what a nightmare of inefficiency and lack of capability that
lack of conformity can produce.
• Reply
• Back to top
Re: Architecture of resources ? by `Mike Schinkel'
Also to Stefan's reply, your proposed "/search" is stated as a verb and for
REST you should use a noun if for no other reason that it puts you in the
RESTful frame of mind.
In the "customer" cases you mention I'd say use "/customers" and "/customers/
123/orders"
After all you can think of a URL as just a generalized query mechanism in many
ways. The URL is really supposed to be an opaque string but because of web
server implementations many of us have been conditioned to think of URLs are
being directories and filename, even in the case of dynamic output from such as
.jsp, .php, .aspx, etc. The URL really should just represent the resource whose
representation it returns when dereferenced and hide how the representation is
prepared on the server as the client really doesn't need to know. There is no
need for a special "search" metaphor.
So for your latter "order" cases, you can use "/orders/last10" and "/orders/
thru-2006-12-31" or if you just call "/orders" use paging as Stefan suggested.
• Reply
• Back to top
Re: So IOW, this applies only to web projects. What about Windows projects? by
`Mike Schinkel'
Exactly, and I think there would be huge benefit to building "RESTful" desktop
applications using OOP objects that all descended from a base class of
"Resource" as in Stefan's example. If I had time to play with this I'd love to
create such a framework.
• Reply
• Back to top
Re: So IOW, this applies only to web projects. What about Windows projects? by
`Florian Schwarz'
What about the Restlet project (www.restlet.org/)? It's focus is on Web
development but it can also be used for desktop applications. All of it's core
classes subclass the 'Uniform' class, which represents a uniform interface with
the HTTP methods GET, PUT, POST etc.
• Reply
• Back to top
Question about use of Cookies by `Matthias K.'
On several occasions I have read that using Cookies would violate the REST
principle of stateless interaction. I don't really see why this is necessarily
true.
As far as I understand, the demand for stateless communication only concerns
the state of resources, and not client or application state. However, the most
typical use of a cookie, namely storing user preferences or session data, does
for one not concern resource state, but application or client state.
Second, all required session data can be carried around in the cookie itself,
and not just be stored in the server memory identifyable be a session key (as
is the case with e.g. Servlets). In other words, I do not see where the mere
use of cookies does not harm server scalability and reliability, if used
properly.
That being said, what are your thoughts about the use of cookies in a RESTful
application? Am I missing something?
• Reply
• Back to top
Re: Question about use of Cookies by `Stefan Tilkov'
I don't think you are missing anything. In my opinion, cookies themselves don't
violate REST principles. Using cookies to store a key that identifies an entry
in a server-side session state data structure does.
• Reply
• Back to top
Re: Question about use of Cookies by `m k'
I would follow the last comment up by saying that a cookie may hold a
server-side session id, but the session id itself can also be something exposed
in a RESTful way. For example, a cookie value could be example.com/sessions/
12345. Taken by itself, isn't a server-side session just another resource (or
noun), except perhaps that its guts are only exposed internally to application
(s) requiring a session?
• Reply
• Back to top
RESTful transaction service by `Ian Goldsmith'
I'm beginning to get a grasp of REST principles and contraints, but am
struggling with one particular example.
I'm trying to model a service that manages checking accounts, providing some
very basic capabilities. The basic resource is an account, which has an id and
a set of attributes. This is easy to model:
GET /accounts - will return an XML doc listing all the accounts as REST
resources e.g. /accounts/{accountid}.
GET /accounts/{accountid} will return an XML document that lists all the
attributes (for now lets assume the only attribute is the balance of the
account).
What I want to create is a set of methods for "withdraw", "deposit", and
"transfer". Clearly I could create these using documents for each method and
POST them to the account, e.g.:
POST /accounts/{accountid}
{value}
This doesn't seem to follow the REST contraint of using a common set of methods
though. To be more RESTful, I guess I would have to PUT a new balance value to
the account (at least this would be idempotent), but this gets clumsy quickly,
especially for transfer, given the different authorization levels required
(it's easy to see a case where I would have different authorization levels for
deposit and withdraw for example).
Am I missing something obvious? Is there an easy way to implement this type of
service?
Thanks in advance,
Ian
• Reply
• Back to top
Re: RESTful transaction service by `Stefan Tilkov'
Ian, you might want to think about modeling the (trans)actions you describe as
resources in their own right. E.g. you could create a new transaction via POST,
get back the URI in a Location header, and then PUT the state information
(including from where to withdraw and where to deposit).
• Reply
• Back to top
Re: RESTful transaction service by `Mark Little'
I mentioned in my presentation at QCon London that we (HP) did some work on
RESTful transactions back in 2000. Well the specification still exists and if I
ever find time I'm intending to re-implement it on RESTeasy. I'd be glad to
discuss this if you're interested.
• Reply
• Back to top
Send large result set by `John John'
hi all,
do you have any idea how to send large result sets?
request:
GET /user
server returns 10 000 records with links. It is bad practise to return all
records to user. I think one of the solution can be: send to user "HTTP/1.1 303
See Other" response and to location header set domain.com/user?range=100,1000,
which means that resource contains records from 100 to 1000. Does anybody have
idea how to solve this problem ? It is good to solve it with 303 status code?
thx..
• Reply
• Back to top
Do you suppose that all possible actions can be reduced to 4 verbs? by `Mark
Kamoski'
Do you suppose that all possible actions can be reduced to 4 verbs?
• Reply
• Back to top
Use of Accept to define required representation by `Martin Haigh'
I also think this is a great introduction to REST, thanks. I am however
struggling with the use of the request Accept header to define the
representation required. The Accept header defines the Content-Types that are
acceptable and is often a list. Whilst this header could be specifically set by
a custom client, somthing like a browser defines a list of values (often 3 or
more). Would in not be better to have the representation required defined in
the URL as part of the ID for example (../customer123.pdf). That way a user
could explictely point their browser at an HTML, SVG, PDF, etc represention as
they wanted?
• Reply
• Back to top
Re: Use of Accept to define required representation by `Stefan Tilkov'
Martin, you can do either or both - it's entirely acceptable to do both content
negotiation and have additional, explicit resources in case you want to be able
to link to specific representations.
• Reply
• Back to top
Rest URI design with URL parameters by `Thomas Tkac'
Hi,
I designig REST web APP and I want to apply some operations on resource op1,
op2, op3 which have one or two arguments.
I want to apply this operations in one request
sample:
GET /resource?op1=name&op1=name2&op2=aa,bb&op1=name3
in order which is in request
at first op1 then op1, op2 op1 with arguments (values)
Is this good practise or do you have any suggestion recommendation how to solve
this problem?
thx
• Reply
• Back to top
UML Diagrams by `Ersoy Hasanoglu'
In which application you drew those beautifull UML diagrams?
• Reply
• Back to top
Re: UML Diagrams by `Stefan Tilkov'
Ersoy, I can't imagine you're still interested in an answer. But if you are: It
was OmniGraffle on Mac OS X.
• Reply
• Back to top
Re: UML Diagrams by `Ersoy Hasanoglu'
Much appreciated. Thank you Stefan.
Kind regards.
• Reply
• Back to top
Re: UML Diagrams by `peng zhang'
Nobody Understands REST or HTTP, Please refer blog.steveklabnik.com/2011/07/03/
nobody-underst...
and www.mfrbee.com/trade/
• Reply
• Back to top
Re: REST on .NET? by `Vlad Bezden'
Ole,
If you still looking at .NET REST framework, I would recommend WCF Web API.
Very nice and clean framework, the one I like most from all previous MS
implementations.
• Reply
• Back to top
well writen, and very easy to understand! by `phoenix bai'
thanks for the brilliant piece!
• Reply
• Back to top
REST & standard behavior by `Dan Noonen'
I have a question about the word "standard" in reference to REST & RESTful
HTTP. As a backdrop for the question, consider all of the apparently valid
approaches suggested in the context of the "RESTful with many parameters"
question. If the world of REST and RESTful HTTP provide many different options
to achieve the same goal, won't we continue to find ourselves in a situation
where a bunch of server specific logic gets coded into clients. "I know that
for this site I need to do it THIS RESTful way in order to make the right thing
happen and for that site I need to do it THAT RESTful way". This doesn't feel
much different to me than SOA and the plethora of service specific interface
logic one has to code against when dealing in that space. What's the benefit of
using a few standard commands like GET, POST, etc. when you still have to wind
down to managing server specific constructs in order to achieve anything
meaningful?
I'm guessing I haven't made that mind-shift that's mentioned just yet & I'm
hoping some replies will help.
• Reply
• Back to top
Re: well writen, and very easy to understand! by `Stefan Tilkov'
Thanks, much appreciated.