What is REST?    (1TM)

REpresentational State Transfer is a term coined in Roy Fielding's dissertation to describe the the existing architecture of the web. The relevant chapter contains a great deal of discussion, but it isn't until quite a way down the page that he summarises REST thusly:    (5EL)

REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.    (5EB)

What is Stateless Interaction?    (5EC)

Interaction is stateless when a single request can be processed without knowing which requests have been made previously. Consider an authenticated request for a person's phone number. You could have a conversation that goes like this:    (5EM)

Me: I would like your phone number, please.    (5EN)

You: Who are you?    (5EO)

Me: I'm your old buddy Frank, don't you recognize me?    (5EP)

You: Oh, well then my number is...    (5EQ)

That's a stateful conversation because I supplied my credentials without resubmitting my request. This next conversation is stateless:    (5ER)

Me: I would like your phone number, please.    (5ES)

You: Who are you?    (5ET)

Me: I'm your old buddy Frank, and I would like your phone number please.    (5EU)

You: Oh, well then my number is....    (5ED)

The benefit of being stateless is that the origin server doesn't have to be the one processing both requests. The second request could be handled by someone else because it is entirely self-contained.    (5EE)

What is a Standard Method?    (5EF)

A standard method is anything with an agreed meaning. In REST we usually talk about GET, PUT, POST, and DELETE. There are many other standard methods defined everywhere from within the HTTP specification to extensions such as Webdav. Incidentally, Webdav defines all of PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. The benefit of using standard methods is really about what happens between a client and a server. Neither one of them really cares what the method is. You could identify a resource that does only one thing and always send it a "DOIT" method, however the caches in-between wouldn't know what to do with the data. If you say "GET" instead, they know they can return data from their own cache and save both bandwidth and latency to you the consumer of the service.    (5EG)

What is a Standard Media Type?    (5EH)

Standard media types are things like HTML, GIF, JPEG. They're formats of commonplace things. Every web browser knows how to render HTML and every image viewer knows how to show you a JPEG. Clients know what to do with them and they don't have to go learn a new format each time they visit a new web site. They are limited to a small set because that's all you can really afford to have when you need to write clients that can process everything on the internet.    (5EI)

There is some merit to saying things like XML are standard media types. The difference between these and the traditional REST media types is they don't come prepackaged with a data model like a JPEG image or HTML page do. They might mean anything. If you're a client that knows what it means, then great. However in the absence of data models to go with the data format the idea of a standard media type is diminished somewhat. The bottom line is that data without a data model is like icecream without a cone, but your data model must be something that a critical mass of people want to implement software for if you are going to get anywhere on Internet-scale REST-based architecture.    (5EJ)

Do any alternative definitions of REST exist?    (5H1)

Yes, REST is a term that many people have picked up and applied in their own ways. Here are some examples:    (5H2)

User REST    (5H3)

When Savas Parastatidis says that AJAX breaks REST he means that users don't see Uniform Resource Locators (URLs) in their web browser's location bar. URLs are an important concept in REST. Exposing them to the user means they can bookmark pages easily, email links to their friends, and otherwise easily refer to and communicate the place they are at on the Internet.    (5H4)

Andrew Newman counters, saying "REST is a way to expose services and AJAX is a way to write client software - they can't really effect one another." Andrew is right that AJAX doesn't break REST, but it may break User REST.    (5H5)

User REST is a valid subset of REST philosophy. It fits within Fielding's criteria and adds its own extra criteria.    (5H6)

No URI Construction REST    (5H7)

URI construction is where you take a URI and you take client knowledge to build another URI. A simple example is the use of favicon.ico on popular web sites. The web browser takes a full URI, such as "http://example.com/myresource" and uses the example.com part of it to find "http://example.com/favicon.ico".    (5H8)

No URI Construction REST does not permit this kind of URI construction. In this view URIs are opaque and cannot be understood by the client, only looked up. This approach allows servers to vary their URI spaces without breaking clients, however the full URIs that every client might want to find must be delivered intact from the server by some means.    (5H9)

No URI Construction REST is a valid subset of REST philosophy. It fits within Fielding's criteria and adds its own extra criteria.    (5HA)

Any HTTP REST    (5HB)

A view among many people who have heard the REST buzzwords is that any use of the HTTP protocol without using SOAP or another RPC protocol on top of HTTP is RESTful. Either by adding arbitrary methods to HTTP or by wrapping up non-standard encodings of function calls they reintroduce the object-oriented RPC style on top of HTTP. REST is a deliberate set of restrictions on Object-Oriented style, and without those restrictions some of the benefits of REST are not realized.    (5HC)

Any HTTP REST is a superset of REST. It is not a valid subset of REST philosophy because many applications of Any HTTP REST don't fit Fielding's criteria.    (5HD)

Who's behind REST?    (1U1)

RoyFielding first described REST in his dissertation. In addition, work on explaining and testing the limits of REST is being done by MarkBaker, JeffBone, PaulPrescod, the RestWikiContributors, and many others. Tim Berners-Lee also wrote some things he called axioms, some of which are core to REST. (However, others are not, for example, static assumptions about content: "to return differing information for the same URL must be considered a form of deception. It also of course messes up caches." But HTTP 1.1 "Vary" header is an example of a REST-like adaptation.)    (1U2)

Is there any published literature about REST?    (1U3)

In addition to Roy's dissertation, there is an overview article entitled Principled Design of the Modern Web Architecture. A list of other RestResources is also maintained here.    (1U4)

Is REST better for my app?    (1U5)

REST appears to make Web apps more likely to create successful matings with other Web apps. Successful matings make Web apps have a larger effect on the Web as a whole. So on the large scale we tend to see lots of RESTy apps.    (1U6)

But on the small scale, it doesn't matter: your boss just wants the damn thing on time and under budget.    (1U7)

This is the same as the split between genes wanting everybody to reproduce, and the real possibility that reproducing won't make an individual any happier. If your goal is to build a web-accessible toolkit that a lot of people make use of, REST may help. If your goal is to build a one-off project that is restricted to a limited group of developers, REST may be irrelevant (but may not be either).    (1U8)

What do you mean when you say RPC?    (1U9)

We mean that each developer defines their own methods and makes them available for remote invocation over the Internet. With this definition, REST can be said to use RPC, because it defines the methods for the developers so that they don't have to worry about them. But that comparison is not often made.    (1UA)

Most applications that self-identify as using "RPC" do not conform to the REST. In particular, most use a single URL to represent the end-point (dispatch point) instead of using a multitude of URLs representing every interesting data object. Then they hide their data objects behind method calls and parameters, making them unavailable to applications built of the Web. REST-based services give addresses to every useful data object and use the resources themselves as the targets for method calls (typically using HTTP methods).    (1UB)

Are REST and RPCs incompatible?    (1UC)

Except for the proviso in the previous FAQ item, and that REST provides for defining new methods (as long as they operate on resources), then the answer is yes. REST is incompatible with "end-point" RPC. Either you address data objects (REST) or you don't. You can try to contort RPC protocols into working on data objects identified by URIs but then you end up re-inventing a non-standard variant of HTTP; WS-Transfer is one example.    (1UD)

Is SOAP incompatible with REST?    (1UE)

See HowSoapComparesToRest    (1UF)

Is the concept of Web Services incompatible with REST?    (1UG)

One answer is that there is no firm definition of WebServices. But REST seems to be compatible with most of the definitions floating around. It is not compatible with definitions that take SOAP-RPC as a starting point. (but then why would you define the problem space around an implementation technology?)    (1UH)

Most applications that call themselves "web services" use an end-point RPC philosopy.    (1UI)

How do REST and P2P compare?    (1UJ)

REST would be extremely useful for P2P, and has already been used for it. See what Endeavors Technology have been doing with Magi at http://www.endtech.com. Or KnowNow.    (1UK)

Don't you think REST needs a catchy marketing retronym, so it doesn't look so gear-headed when it appears on the same page with SOAP?    (1UL)

Really Easy Semantic Translation?    (1UM)

Sure, sounds good. Propose some.    (1UN)

>>> REST of US (as in, join the rest of us in supporting the clearly superior alternative).    (1UO)

So what do the HTTP methods mean then?    (1UP)

Roughly, GET means "get" and DELETE means "delete". The meaning of PUT and POST, and the differences between them, isn't quite so clear cut unfortunately, so a couple of standalone attempts have been made to explain it.    (1UQ)

See MarkBaker's definition. Mark's diagram makes this clear (implicitly).    (5SG)

Elliotte has worked this one out.    (64E)

MinimumMethods is an attempt by Benjamin Carlyle    (64F)

Mike D also came up with a very pragmatic definition;    (5SL)

Don't think in terms of create or update - think in terms of transfer.    (5SM)

If the client knows the identity/destination of the resource - use PUT (or DELETE).    (5SN)

If the client doesn't know the identity of the resource, but knows of a helper resource that will 'just take care of it', then use POST to that helper resource.    (5SO)

Also see ThingsPostCanDo.    (1US)

What if I need to do a GET but my query is not something that can be fit into a URL?    (1UT)

MarkBaker has addressed this and defended it in discussion. Someday somebody should write a more unified discussion of this design and its defence. But in the meantime, ask yourself how often this problem arises in real-world situations. GET is restricted to a single-URL line and that sort of enforces a good design principle that everything interesting on the web should be URL-addressable. If you want to make a system where interesting stuff is not URL-addressable then you need to justify that decision. Typically "contorting" your application around GET's limitations makes the application better by forcing it into the web architecture.    (1UU)

How does HTTP handle reliable delivery?    (1UV)

You can do reliable delivery in HTTP easily at the application level. The guarantees provided by TCP get you quite far and then you need just a little bit more. PaulPrescod discusses some of the issues in a document called Reliable delivery in HTTP.    (1UW)

There are some proposals for standardized extensions to HTTP for reliable delivery. HTTPR is one, but it isn't very popular with the REST crowd. It seems like a port of MQSeries ideas rather than a solution that specifically benefits from HTTP's strengths.    (1UX)

Other proposals for reliability come from Yaron Goland (SOA-Rity), Bill de hÓra (HTTPLR) and Mark Nottingham (POE).    (68B)

How does HTTP handle asynchronous delivery?    (1UY)

There is no standardized solution yet. You need an HTTP extension. The outlines of one were discussed on rest-discuss. Also, you should probably learn about Adam and Rohit's work on notify.    (1UZ)

How does HTTP handle transactions: multiple step commands that are rolled back together if any one fails?    (1V0)

Good question...while you wait for an answer let's ask how SOAP, XML-RPC etc. handle transactions? The answer is mostly: "it is the client's responsibility". I think that's the REST answer also. The database concept of transactions does not scale well to the Web because clients will start transactions and then just forget about them. This doesn't just tie up server resources: it also has severe locking consequences. Essentially some other user could be locked out waiting for the transaction to complete. On the other hand, if the clients take full responsibility for reversing their own transactions then the server will not try to do any locking etc.    (1V1)

How would REST work for B2B ecommerce collaborations (e.g. ebXML)?    (1V2)

Pretty well I'd expect :). ebXML TR&P doesn't make the best use of HTTP or REST, but it's better than most.    (1V3)

ebXML TR&P uses POST in only one way, as you would use it to process an HTML form. The URLs are not required to identify resources per se, but just act as mailboxes for receiving these messages.    (1V4)

A good test of REST-fulness (though not complete by any means, since HTML forms fail) is, can I do a GET on the URLs that I POST to, and if so, do I get something that in some way represents the state of what I've been building up with the POSTs?    (1V5)

For ebXML, the answer is "no". ebXML assumes that the POSTed documents disappear into each trading partner's internal business systems. However, the business process would actually work better if it was treated like a Web resource, for example an order resource, where all of the subsequent POSTs such as shipments, payments, etc. became sub-resources. Amazon puts your order on a Web page where you can track its status. B2B ecommerce is sometimes not so nice.    (1V6)

Where does WebDav fit in to all of this? A useful application of REST, or something stronger?    (1V7)

See WebDav.    (1V8)

How do REST and Jabber compare? Jabber has some useful characteristics that will be invaluable for next-generation internet-based applications.    (1V9)

Jabber's protocol more tightly couples client and server than would be done with HTTP/REST. What specific characteristics did you have in mind?    (1VA)

Why are Magi and KnowNow RESTful and Jabber not? Jabber doesn't identify resources, assign URLs, and use HTTP to access them. They have their own protocol. Magi's means of doing IM does do those things, as does KnowNow's KnowBuddy. KnowNow also uses POST and GET in their router in a special way that is quite powerful. Basically, they publish URLs which identify "topics". POST is used to ask that a topic accept a message "as a subordinate". The state of the topic, i.e. the composite of all messages received to the topic so far, can be returned with GET. A great use of REST, that is so powerful, but done as a special case of it, not an extension.    (1VB)

Can REST really beat RPC when the whole software industry is pushing RPC-like solutions?    (1VC)

If REST works and RPC doesn't then yes, REST can win. Some of us believe that. Notice how the course of SOAP started as pure RPC and has been moving further and further away from it? Perhaps that is early evidence of an industry-wide shift. Also, how many RPC-based web services are really deployed and in-use on the Web? SOAP and XML-RPC have been around for years and yet there is no killer app! REST can point to the Web itself as proof that it works. If you want to see REST used with XML then I'd suggest you look at Meerkat, which is a massively scalable application, incorporating content from hundreds of sites. It does so by using plain old HTTP. Is there any equivalent SOAP or XML-RPC API that is widely implemented, massively interoperable and highly useful? http://www.weblogs.com is good.    (1VD)

What does a REST message look like?    (1VE)

REST is just an architectural style. HTTP is the protocol that is most in tune with the style, and the one used by the largest REST application, the World Wide Web. URIs are the addressing mechanism for that application. REST can support any media type, but XML is expected to be the most popular transport for structured information. REST is already used today with HTML, XHTML, RSS and various proprietary XML vocabularies. Unlike SOAP and XML-RPC, REST does not really require a new message format. Just use HTTP and the most appropriate XML vocabulary!    (1VF)

I need my app to work with non-HTTP protocols. Does REST still apply?    (1VG)

Short answer - Yes. The concepts apply in general to any system. However, there are problems that can be solved more cleanly or more quickly with other non-or-partially-REST approaches - you need to understand the different approaches and decide for yourself. You have to really, really be sure you don't want to participate in the Web though. The larger or more 'fundamental' the system is that you wish to create, the more you should use REST and even full HTTP.    (1VH)

Other prototocols are not organized around URIs the way HTTP is. This means they tend to balkanize the address space into email addresses, jabber addresses, etc. They also do not have this concept of manipulating resources described URIs. In other words, it is probably best to use HTTP.    (1VI)

Are you sure you need your app to work with non-HTTP protocols, or is that just what you were told? Perhaps if you read the rest of this page you'll learn to use HTTP in ways that obviate the need for other protocols. Consider carefully how hard it is to deploy new protocols across firewalls. If HTTP can be used for instant messaging (Magi), content management (WebDAV?) and P2P (see above) then what did you have in mind that is outside of its scope?    (1VJ)

If you really do need non-HTTP (e.g. to talk to a village in Zambia with only UUCP access) then have you considered tunnelling HTTP over that protocol? HTTP is pretty simple...basically just a couple of headers and you are done!    (1VK)

Don't asynchronous applications require an asynchronous protocol like SMTP?    (1VL)

Unfortunately the word asynchronous is very overloaded. Some people are thinking about an implementation technique. Some are talking about an application structuring technique. A very few people are really thinking about what it means for an protocol to be asynchronous. Consider these thoughts from Jeff Bone. The gist is that most protocols (including SMTP) are synchronous but it is at the application level that things become asychronous. This can be done using HTTP also. We are working on standardized conventions in our HttpEvents document.    (1VM)

What about REST/HTTP and security.    (1VN)

They go together like peas in a pod. Consider these references: Mark Baker and Paul Prescod.    (1VO)

If Web Services are doomed, how will machine-to-machine integration occur on the Web?    (1VP)

Why, the Semantic Web of course!    (1VQ)

You have to understand that the Web already supports machine-to-machine integration. Google's Googlebot is a software application which walks and indexes the Web, extracting machine processable information from the mostly machine-processable-info barren Web that exists today. It doesn't need a human to know that "address" in HTML is a mailing address, or that META author tags include the email address of the author. But certainly the Web is in need of much more information like this. That's what RDF, and related (RDF Schema, DAML+OIL, etc..) technologies provide; a language that can be used to relate information in a machine processable manner.    (1VR)

Remember, what's not machine processable about the current Web isn't the protocol, it's the content.    (1VS)

What about those pesky hit counters?    (1VT)

REST systems have a safe and idempotent 'get' operation. So does HTTP. 'Safe' generally means it isn't intended to modify the resource (the sender isn't responsible for any problems), and 'idempotent' means repeating the operation ends up with the resource in the same state (it doesn't mean all the responses are always identical).    (1VU)

This is a confusing point because a 'hit counter' accumulates the number of time an idempotent operation has occured - and often is visible within the representation of that resource - things change just by doing a GET! Horrors!    (1VV)

There is of course no way to prevent this from mere architectural descriptions of the system. It is up to the server author to understand what will happen and what this implies. The REST approach guides designers away from this approach as a foundation to build functionality. It is still doable - but it has costs and problems that it should be avoided as a general approach.    (1VW)

What does REST mean by "stateless"?    (1VX)

First, some quick context. There are two kinds of state; application state and resource state. The latter is the most obvious and visible form of state; the "representational state" that REST refers to is resource state. The former, application state, refers to that information necessary to understand the context of an interaction. So "my authorization info" is application state. REST includes the "stateless" constraint, which says that all messages must include include all application state.    (1VY)

Followup questions:    (1VZ)

Wouldn't the context of an interaction include both the message addressed to a resource and also the state of the resource being addressed? For example, the resource may not exist, may disallow DELETE, may require authorization, etc.    (1W0)

To complicate the question a little more, what if the resource allowed one and only one interaction of a particular type, for example, POSTing a response to a test question. In this case, the interaction depends on a sub-resource hyperlinked to the resource being addressed. I.e. where is the acceptable boundary of RESTful interaction?    (1W1)

It's hard to make super-clear deliniations ... let me try these points:    (36H)

Roy Fielding attempts to explain what REST means by "stateless", as well as implications for cookies and sessions: http://groups.yahoo.com/group/rest-discuss/message/3583    (1W2)

What about Cookies?    (1W3)

Cookies are a receipt for application state handed out by the server. Using them necessarily means being stateful, because not all application state is carried in the message; that part of it to which the cookie refers, is held on the server.    (1W4)

Note that one of the benefits of statelessness is still maintained with cookies; there exists a reference to the state. This means that the request can, for example, be load balanced to some other server within the same trust domain for processing, and it will likely be able to interpret the cookie. Beyond that trust domain, cookies are not likely to mean anything to anybody though.    (1W5)

What about Sessions?    (1W6)

Application state = session state. If you want a session, you need smarter clients. For browsers, today, this is a non-starter. But for non-browser environments, there's likely very little need for cookies, and only a need for clients to manage state (application and resource) better. For example, if doing machine-to-machine purchasing, a client could send a single HTTP request that included descriptions of everything it wanted to purchase in one message, rather than doing it shopping-cart style where the server had to track that.    (1W7)

What is a recommended REST Reading order?    (1W8)

I started with articles by Paul Prescod at Prescod.net    (1W9)

Why has there been no actual content added to this Wiki for the past 90 days?    (1W10)

Hopefully because the Wiki is mature enough to answer a lot of questions that people have about REST.    (35X)

Where can I find applications that follow the REST ideas?    (35W)

For human-to-machine, it's hard not to find RESTful apps on the Web, at least if you ignore cookies (the one widely deployed, non-RESTful aspect of the Web). I've always liked Yahoo Groups as a site that doesn't (appear to) use cookies, and has a well designed and maintained URL hierarchy.    (35Y)

For machine-to-machine, the most obvious is Amazon's RESTful "Web services", but there's other sites that, for example, return machine processable data on GETs. Certainly a lot of Semantic Web services do that. For example here's one that returns airport info when you provide the airport code.    (35Z)

Are there any lists of RESTful Web Services? Like xmethods.net does for SOAP?    (3D4)

A Google search of "http get" on the http://www.webservicex.net site turned up a great list.    (3IA)

Discussion    (5HE)

Please discuss the page in this section.    (5HF)