This is an archive of past discussions about REST. Do not edit the contents of this page. If you wish to start a new discussion or revive an old one, please do so on the current talk page.
Until yesterday, I had never heard of REST, and had no idea what it was. after browsing on from the external links that were already here, however, I felt I had a rough "feel" for what it was all about. I could, however, be completely wrong, so if anyone comes along and wonders why the article is so up the spout, it's because I wrote it from scratch based on nothing more than a few hours web browsing. Hopefully, though, it's better than what was there before. - IMSoP 19:55, 11 Jan 2005 (UTC)
REST without XML
This article seems to assume and imply that in REST only XML is used in combination with HTTP, which is actually not true, REST does not require using XML in any way. At least that is how I understand it.
I disagree. Of course REST is an architectural style, a set of abstract constraints, which are applied to a network application architecture. It's the original definition by Roy T. Fielding in his Ph. D. dissertation. But in real life REST refers usually to a set of specs such as HTTP (in a stateless manner, according to request/response MEP), XML, RDF, etc. It's clearly described in second paragraph of the article. So real-life REST implies this specs. — Anrie Nord2006-07-26 20:44Z
I copmpletely agree that REST has nothing to do with XML. The WWW is RESTful (that is in fact the core message of his thesis), and it serves up HTML and all sorts of other formats that are not XML. Goflow620604:33, 9 January 2007 (UTC)goflow6206
REST is an architectural style for distributed hypermedia systems
I can't believe this aspect of REST receives so little emphasis, when it is so essential to understanding HOW and WHY Roy Fielding composed a set of disparate styles into REST. Here's whatRTF himself says: "Although our discussion of architectural styles will include those applicable to a wide range of network-based systems, our evaluation of each style will be based on its impact upon an architecture for a single type of software: network-based hypermedia systems. Focusing on a particular type of software allows us to identify the advantages of one style over another in the same way that a designer of a system would evaluate those advantages. Since we do not intend to declare any single style as being universally desirable for all types of software, restricting the focus of our evaluation simply reduces the dimensions over which we need to evaluate.Evaluating the same styles for other types of application software is an open area for future research." [emphasis added]--Nick 18:02, 8 Jun 2005 (UTC)
It's very difficult to understand. This is supposed to be an encyclopedia where people can easily understand things, not an expert's reference! Perhaps a "Simple English" version is needed.
I don't get it either. If not for the article's emphasis on saying "this is not RPC", I would have thought that REST and RPC are exactly the same thing, but written with different syntax. 130.167.236.153 (talk) 20:28, 9 October 2008 (UTC)
I now only "get it" having read the short article at http://www.xfront.com/REST-Web-Services.html. Unlike your predominately abstract ramblings on Wikipedia, the xfront article covers REST in an example-driven and concise way. REST's value is a function of how unambiguously and clearly you can explain it; at present you fail.
User:WmWallace 15:18, 20 June 2009
WmWallace: that's not an accurate article. It talks too much about URI structure, while REST actually does not care what your URIs look like. It also doesn't seem to talk about hypertext-driven URI navigation. —Preceding unsigned comment added by170.171.10.30 (talk) 21:59, 11 August 2009 (UTC)
Discovery
The following paragraph is not entirely accurate:
Note, however, that the HTTP verbs do not provide any standard method for resource discovery -- there is no HTTP LIST or FIND operation, to correspond with the list*() and find*() operations in the RPC example above. Instead, REST data applications work around the problem by treating a collection or set of search results as another type of resource, requiring application designers to know additional URLs or URL patterns for listing or searching each type of resource.
A quick perusal of the RFC for HTTP shows there is a standard method for discovery -- if not for discovering resources, then for discovering what methods a resource supports. OPTIONS is the HTTP method in question, and is described as:
a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.
Therefore, an Allow header in an OPTIONS request would seem to provide the level of discovery the author talks about in the original paragraph.
Both REST and RPC address the problem of dividing control of program flow between local and remote network nodes in distributed operations. If control is local, it's RPC, if control is remote, its REST. The concept isn't new, I first heard of it from one of the designers of the X.25 protocol in the early 1970's.
Think of it this way. You are at one location on the network, and you want to perform some series of actions at another location based upon a set of data you have at your current location.
You have a choice of:
1) Analyzing the data locally and requesting each action at the remote node individually.
2) Sending the data to the remote node, and letting the remote node figure out what actions to take.
The first option is RPC (remote procedure call) because the actions (procedures) at the remote node are being called (invoked) remotely from the local node.
The second option is REST (Representational State Transfer) because you are transferring the local data (which is the representation of the initial state) and the the actions at the remote node are being called from the remote node. It differs from RPC in that once the initial data (state) is transferred, the local node knows nothing of what happened because the remote node has control of the state.
Nothing to do with state, but still a violation of REST.
REST frameworks
I would be useful to mention some frameworks that help to build RESTful applications:
- Gomba(Java): RESTful Servlet-based interface between relational databases and the Web
- NetKernel (Java): Resource oriented microkernel and RESTful application server
- Restlet (Java): Lightweight REST framework and alternative to Servlets
- Jersey (Java) : JAX-RS (JavaTM API for RESTful Web Services : 311) Reference Implementation for building RESTful Web services —Preceding unsigned comment added by Jcronier (talk • contribs) 18:58, 29 January 2008 (UTC)
- Tonic (PHP): RESTful Web application development and Web site management
- Waterken (Java): Use the Waterken Server to create and deploy RESTful web services
- RESTEasy: RESTEasy is a JBoss project that provides various frameworks to help you build RESTful Web Services and RESTful Java applications. Marcosvm (talk) 00:31, 18 June 2009 (UTC).
- Catalyst: Perl's MVC web application framework with its Catalyst::Controller::REST add-on —Precedingunsigned comment added by Archpollux (talk •contribs) 20:09, 24 July 2009 (UTC)
The article mentions, as a claimed benefit, that REST "Requires less client-side software to be written than other approaches, because a single browser can access any application and any resource".
However, most (if not all) browsers are limited to HTTP GET and HTTP POST, while HTTP REST argues the four CRUD operations (Create, Retrieve, Update, Delete, whose mapping with HTTP methods is PUT, GET, POST, DELETE respectively) are needed to provide a generic interface that is enough for any application. See REST wiki's Minimum Methods article for more details.Juanjobnt07:43, 29 August 2006 (UTC)
REST is based around the use of standard methods and standard content types. The Web applies this by choosing GET at the most important method (most requests in any large information system are queries, rather than updates). It then also imperfectly applies the PUT, POST, and DELETE method. Imperfectly, because not all of the technologies we use on the web support these methods and not all of them use the methods in a minimal way. Some would say that the web tends to apply a "low REST" in that POST is used to tunnel arbitrary requests. Whether this is a bug or a feature of the web is still a matter for debate that we may not settle for some time. REST itself does not really dictate either the "low" or "high" REST method sets, only that they must be standard set.
Just as REST is an idealisation of the web, this claimed benefit is of an idealised browser. A browser that knows how to GET, PUT, POST, and DELETE content in a known set of types is capable of dealing with applications that accept those methods and represent data in those types. The claim is that it is possible to do banking over the web, control sattelites over the web, view maps, book flights, buy books, and do a myriad of other things using only a single browser. This is achieved on the web by agreeing on a small set of methods (primarily GET, then POST, then others) and content types (html, png, etc). The one browser can then access all of these sites. In contrast, RPC would typically require a different client application to be written for each service. The existence proof of the web shows that it is possible to use a generic browser to access all possible services, possibly using code-on-demand for some special features.
fuzzyBSc 2006-09-15T22:32:27+10:00
HTTP verb relationship to cut-and-paste
this September 5 update removed the cut-and-paste analogy for HTTP verbs. I have added the analogy again as of September 9, this time with some supporting explaination. I suggest further discussion on the topic move to here before any more in/out edits occur on this topic.
I may have been the first person to suggest this analogy, and I accept that CRUD is better established. I think there is value in the cut-and-paste model, especially when answering questions like "How does REST do transactions?"
"The term is also often used in a looser sense to describe any simple interface that uses XML (or YAML, JSON, plain text) over HTTP without an additional messaging layer such as SOAP."
SOAP is one way (or format) to implement a web service, so the term "web service" doesn't imply using SOAP. The SOAP approach is to express your methods through a strictly defined XML document which is transferred over HTTP. Therefore it adds an additional layer - unlike the REST approach which would use HTTP-methods to express what kind of action you want to perform and only transfer a representation of a resource (as XML for example) in the content part. --Shepard17:59, 10 July 2007 (UTC)
My first reaction to this change was emotional. I was kind of attached to the old content, which had reached a state where I was comfortable directing people to as a statement about what REST is. My second reaction was that the architectural constraints and advertised benefits section both seem less clear than they were before. The architectural constraints section because REST jargon such as "stateless" have been completely replaced by less precise definitions, the advertised benefits section because explaination has been removed. I have placed a one week embargo on myself editing any content on the page until I am more comfortable and familiar with the direction the page is taking. In the mean-time I am attempting to move the old content to RESTwiki.
-Benjamin Carlyle Sun Oct 22 07:43 2006 (UTC)
Etan: I like your layout much better and support using it to replace the current version. I'm still new to being a Wikipedia editor so I'm not familiar with the editorial process. See my additional comments:
I am trying to use XForms to call web services and a lot of the very useful examples of REST interfaces were lost in one of the priort edits :-(. I put them back on a seperate page. I think a this list of sample REST interfaces that can be called directly from inside a web form is very helpful for students learning XForms and REST. Please take that into consideration.
The following text has been added to the introduction:
"REST is typically used for calling a remote service by passing parameters using a URL"
This text is imprecise and incorrect. REST is an architectural style. It isn't used for calling a remote service. HTTP is the protcol you would use to call a remote service. URLs sometimes contain parameters when constructed from a web form, but this is not typical REST style. REST is a post-RPC communication pattern than focuses on transfer of state (aka information) over a uniform interface of constrained methods and content types rather than invoking arbitrary functions with arbitrary parameter lists.
To quote Mark Baker:
In your opinion, what is the one thing that most clearly separates REST from SOA? The answer I gave was… generality. If you ignore identifiers, hypermedia, and all those other Webby things, and just look at REST and SOA as two architectural styles, the main difference is that REST internalizes the best practice that generalized interfaces are better
I agree that this is precise, but does not appear to be very useful to most novice users IMHO. Perhps we come up with a more useful desctiption that might be useful to typical newbie to REST such as a student without a computer science degree, a BA or a PM that hears REST in a meeting and uses Wikipedia to look it up.
The acronym REST stands for Representational State Transfer, this basically means that each unique URL is a representation of some object. You can get the contents of that object using an HTTP GET, to delete it, you then might use a POST, PUT, or DELETE to modify the object (in practice most of the services use a POST for this).
Not that this is a precise definition but it does give a newcommer some idea what a REST interface is and how it might be different from a SOAP interface.
The quotation gives a newcomer a wrong idea about REST if the quotation gives any idea at all. The English-language Wikipedia is for a broad audience of people literate in English, so don’t presume that readers know about HTTP, URLs, or SOAP.
But in practice REST is used exactly that way. Let's keep in mind that 99% of the people that want to learn about REST (the simple way to access web services) as opposed to the 1% that want learn about REST (the term used by Roy Fielding to coin his set of architectural constraints). Of course I don't know if it's really 99/1, but it's clearly a whole lot/very few people.
REST can mean different things. Can we please focus on the mainstream one? Because reality is this article is not being that helpful. -- Felipec13:18, 15 April 2007 (UTC)
I removed a bit of spam that was part of the restored version.
I posted clean-up notices. I stopped short of posting a notice to indicate a dispute over factuality, though I dispute the article’s factuality.
I won’t restore the version that I like best so far.
I will write a version (User:Etan Wexler/Representational State Transfer) that has factual basis and thorough references. I will attempt to adhere to the Wikipedia manual of style (tone, audience, jargon, format, copyright). I will revise the main article by copying the factual, sourced version.
As time permits, I will document the main article’s errors and style problems.
I'm afraid many of the same comments as noted on the URL article page also apply to the REST page. Etan, you culled a lot of information.. then asked for contributers to expand. Unfortunately, this resulted in low quality submissions and I suspect put off some longer-term contributers. I think a more constructive engagement is in order.
I think that the REST article did/does need a cull and a rethink. I'm glad to see you are persisting with your version of the rethink. I do not endorse the anonymous revert. I'm a beliver in working from whatever is there now towards a better article rather than trying to solve too many problems all at once or get into a power struggle.
I would be curious to hear what you think are the biggest issues that might be the first that should be addressed. I think the main thrust of your edits is that the article should not focus on a technical definition or an explaination of REST. That such a definition should be included, but that the social impact, history, etc should be given equal weight. Is that accurate? Is there good precedent elsewhere on how technical articles like this should develop and where they should end up?
improved discoverability - you can enumerate the resource http://example.com/forms/find/ and find a full list of resouces that can be found
the resource the form applies to is more clear from the uri, and more trivially parseable
the uri's are more readily partitionable - find forms would be largely static, and could be served from a simple cache, where caching of the rest of the resources would be more complex if done at all
plural indicates you might get more than one result back (and saves you having to guess the pluralisation to find the related resource)
I'm asking rather than editing as I'm new to both rest and wikipedia, so I'm being cautious.
-bob, 12:33, 20 November 2006 (UTC)
Actually, both are poor. Better examples would be:
That would be a list of users/locations to me, rather than a form for finding users/locations. --Shepard18:10, 10 July 2007 (UTC)
Indeed it would, but the list would include some form of mechanism for the client to narrow down that list, such as a URI template. The URIs given above are flawed because they include verbs and though the application itself might behave in a completely restful manner, the presence of verbs in URIs is a bad smell. Here's an example document fragment:
<users search="?q={criteria}" next=";1">
<!-- ...first page of users... -->
</users>
Alternately, the URI template might be given somewhere else. Regardless, a client that understood the document's content type could dereference a search URI without having to resort to construction. --Kgaughan13:47, 27 August 2007 (UTC)
I'd better point out here that I'm treating the site as machine-readable, but a form is just another kind of URI template.--Kgaughan13:50, 27 August 2007 (UTC)
bob, that's quite a bad URI structure. What are you really looking for? Users, or forms? Kgaughan's suggested structure is the way it should be. 201.213.146.51 (talk) 03:40, 25 January 2009 (UTC)
More Practical
IMHO there needs to be a lot of work in order to make this article more practical.
Here is a user version that I find simple, yet informative. Of course, it lacks a lot of information, and it's probably wrong in some aspects as I'm no REST expert, but the idea remains.
Some of these are superficial, but I believe will help clean up the page:
Reduce the number of RPC examples (what REST is not)
Combine sections 1 (REstful example the WWW), Public Implementations, and Outside of the web, these sections contains useful "fluff" as I would put it but do not contribute substantially to the structure and organization of the page imho
Added link to Yahoo about their web services - very practical page about rest
I just read the majority of Fielding's dissertation and feel it would help to clarify that REST is not a specification, is not a protocol, as some may feel an "architectural philosophy" is too ambiguous or abstract to hold much meaning. I also feel it would be helpful to simply remove the Public Implementations and Outside the Web examples altogether (as opposed to my previous suggestion of combining them with section 1), because while the statements issued in those sections may be true, they do not contribute substantially to the substance of this page in its attempt to provide a generalized and universally accepted reference to the "Representational State Transfer" concept. I suggest replacing these sections with a section called "REST Encourages Network Based APIs" or something like that, containing simplified interpretations ofsection 6.5.1 of Fielding's dissertation: Advantages of a Network Based API, and how those apis are manifest in the public implementations and non-www implementations previously mentioned.
I also published the notes I took while reading the paper on one of my blogs which some may find helpful:
I believe the best way to explain that REST "is not a specification, nor a protocol" would be to first accept the fact that outside the circle of few people that know about Fielding's dissertation, REST means easy web services. Fielding coined the term, and used it in a general way, and now we are seeing people using those ideas and relating REST to this easy way to access web services.
So in my opinion REST now has different meanings, the original and the common one. We should explain both, mostly the common one, and for people that want to know in detail the "architectural philosophy" well go to REST (architectural philosophy).
If we do that then it would be easy to understand that REST "is not a specification, nor a protocol", where it comes from and how it's commonly used. -- Felipec12:39, 1 July 2007 (UTC)
WSDL 2.0
With WSDL 2.0 , it is now possible to bind web service over HTTP (without SOAP) to all the http method:
for example, amazon s3 web service, which has a perfect RESTful web service implementation, offers wsdl 1.1 for the soap binding, anything for the HTTP.
With WSDL 2.0 it is (almost) possible, in case of a RESTful web service, to offer two WSDL for SOAP binding and HTTP binding with the same abstract part.
This is important for REST - also because making web services in a restful way it is much simpler. —Precedingunsigned comment added by 151.16.215.179 (talk) 23:49, 17 September 2007 (UTC)
Negotiated Content Type; State Examples; Authentication
As a person learning REST, I would like to see the following expanded upon:
1. Under the topic "Uniform interfaces in REST and RPC", it is briefly mentioned that the content type could be negotiated (XML, CSV, etc.). What is not clear is how it would be negotiated - i.e., is it part of the URI (as inhttp://foo.com/my/resource/csv) or part of the HTTP header? I assume the latter, of course, but for some reason that troubles me: I can't generally specify an HTTP header in a web browser, for example.
2. I'd also like to see some concrete examples showing how an application that uses cookies or server-maintained state can be made RESTful.
The examples show a CRUD-like interface only. Depending how you look at it, this could be both good and bad, but almost certainly needs to be expanded upon, and can probably crystallize the differences between REST and RPC (and the debate).
To demonstrate, I would argue that of much more interest than knowing how to CRUD a document, for example, is how to perform other business operations relating to the document, for instance, approving the document. This may also help uncover contributing concepts and paradigms for the reader (see my other section in this talk page about how the RPC and REST articles need to acknowledge contributing concepts).
Obviously it is good that examples center around CRUD-like idioms, and some people would say that's the whole point. But showing, for instance, that RPC tends to be about the action, whereas REST tends to be about the document.
Please overlook any unintended over-simplification in this suggestion. I just believe these ideas to be important to the comparison.68.98.233.81 (talk) 05:10, 2 January 2008 (UTC)
Both RPC and REST articles needs to acknowledge inherited software design ideas that are independent of REST or RPC
In my section on this talk page about problems with the REST v RPC examples, I suggest that it is more interesting and useful to show examples other than simple CRUD operations, and I gave the example of approving a document.
An example may show, for instance, that "approving a document" is actually a process wherein one "creates an approval", as in, an approval document about another document. In the design of such systems, and particularly easy to show in the design of RPC-like systems, underlying paradigms and idioms, such as object-oriented programming (OOP) show through immediately, but this selection is only partially related to the choice or idioms of REST or RPC themselves.
The debate regarding RPC v REST is sometimes lacking clarity and objectivity, as is generally expected with human nature. Separating out the true idioms of a protocol from those inherited from other software and system design decisions is critical to understanding them.
(As before, please overlook any unintended over-simplification in this suggestion. I just believe these ideas to be important to the comparison.) 68.98.233.81 (talk) 05:10, 2 January 2008 (UTC)
Near as I can tell, based on the article and the confused commentary here, the "debate" between the "REST vs. RPC" has exactly the same structure as the old "procedural vs. object oriented" firefight of previous decades. Perhaps the only difference is that in the latter debate, while everyone understood that at the end of the day programs are programs, the problem was how to express computational intent in a way humans are better able to manage. And to that extent the syntactic sugar offered by the OOP languages had a small but demonstrable benefit re: larger systems of software.
On the other hand, it seems clear to me this REST vs. RPC stuff is mired in confusion simply because there is no real benefit to writing an URL 'host/object/function' vs. 'host/function?object' (or whatever). RPC is RPC, regardless of how it is expressed. So perhaps the difficulty explaining the subtle nuances (see above for many examples!) exist because there isn't anything to explain. Indeed, it strikes me that in the real-world, no one will ever know, or care, whether REST was used to design a system. Further, that if it was ever necessary to know or care, someone, somewhere, has committed layer violations. mdf (talk) 17:42, 8 February 2008 (UTC)
Idempotency
Something that should probably be added: I'm not sure where to find a good reference for this, but all RESTful methods except POST are supposed to be idempotent. That is, it should be harmless to do an additional GET, PUT, or DELETE in the event of not getting a response.
With careful design, one can render even the non-idempotency of POST irrelevant. Basically, you design your service so that the client can do a series of PUTs to some sort of holding zone; then the can POST simply be a command to act on the data that has already been passed by PUTs. - Jmabel | Talk19:20, 2 April 2009 (UTC)
Fielding frustrated about what APIs are called REST APIs
Obviously (see comment #8) he seems not too happy about the Wikipedia article as well:
To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources.
Fielding is quite at liberty to correct the Wikipedia article, if he is concerned that it is not authoritative enough. - Paul (talk) 12:30, 4 May 2009 (UTC)
He has already supplied the authoritative document on REST - it's our responsibility to reference and cite it properly, which we have so far failed to do.
Requested move
The following discussion is an archived discussion of the proposal. Please do not modify it. Subsequent comments should be made in a new section on the talk page. No further edits should be made to this section.
The result of the proposal was no consensus to move the page from Representational State Transfer to REST, per the discussion below. Also note that the proposed title does not currently redirect to this page; other things are also referred to as "REST". Dekimasuよ!10:18, 31 May 2009 (UTC)
As per WP:NC, "Titles should be brief without being ambiguous". This technology is almost always referred to as "REST" and almost never as "Representational State Transfer". This move would lead to a shorter, more manageable title and less confusion for readers. — Hm2k (talk) 09:31, 26 May 2009 (UTC)
Survey
Feel free to state your position on the renaming proposal by beginning a new line in this section with*'''Support'''or*'''Oppose''', then sign your comment with~~~~. Since polling is not a substitute for discussion, please explain your reasons, taking into account Wikipedia's naming conventions.
Mild Oppose: I remember making a similar suggestion in the past for Enhanced Data Rates for GSM Evolution→EDGE; my arguement there was that the backronym meaning of the letters EDGE had changed over time (the latters hadn't). For REST, I don't see a gain from renaming it to "REST" alone, but do think that it should possibly be renamed to be the lowercase "Representational state transfer" to match the introduction, as there is no word to provide the 'E'. —Sladen (talk) 16:27, 26 May 2009 (UTC)
Oppose: It's always referenced as both "REST" and "Representational State Transfer" as I've encountered it … often with the expansion of the name used to emphasise a point about focusing on Representations. I don't think "REST" has quite the status that "laser" or "radar" do. Additionally, technology is a acronym-heavy field, but that doesn't mean the "proper" identifier is the acronym. Looking at the Template:IPstack, for instance, has very few acronyms as names. Clearly, "http://wikipedia.org/REST" should get the user here to this article very quickly, but it doesn't need to be the name. jsled (talk) 03:50, 27 May 2009 (UTC)
The above discussion is preserved as an archive of the proposal. Please do not modify it. Subsequent comments should be made in a new section on this talk page. No further edits should be made to this section.
Removed material
Partially in response to some comments above (e.g. #REST is an architectural style for distributed hypermedia systems and #I do not get it) and partially simply because they were some combination of being rambling, confusing, overly abstract, confused or incomprehensible as well as being uncited and unreferenced, I have removed the following text blocks from the article:
In the strictest sense, REST refers to a collection of network architecture principles that outline how resources are defined and addressed. Usually, however, the term is more loosely used to describe any simple interface that transmits domain-specific data over HTTP, without an additional messaging layer such as SOAP or session tracking via HTTP cookies. These two meanings can conflict and overlap.
- If we start off by saying it has two meanings, then that makes the whole thing confusing. I suggest a separate article for the other meaning (If it legitimately exisis, which I doubt. I think the two usages are by 'those who understand it' and by 'those who don't')
The difference between the uses of the term "REST" therefore causes some confusion in technical discussions.
- See above
Claimed benefits
Many of the statements below refer to REST in the specific context of Web Services, as opposed to SOAP. REST was originally defined in Fielding's dissertation in the context of information and media access. Fielding did not originally contrast REST with RPC.
Some benefits with REST:
Provides improved response time and reduced server load due to its support for the caching of representations
Improves server scalability by reducing the need to maintain session state. This means that different servers can be used to handle different requests in a session
Requires less client-side software to be written than other approaches, because a single browser can access any application and any resource
Depends less on vendor software and mechanisms which layer additional messaging frameworks on top of HTTP
Provides equivalent functionality when compared to alternative approaches to communication
Does not require a separate resource discovery mechanism, due to the use of hyperlinks in representations
Provides better long-term compatibility and evolvability characteristics than RPC. This is due to:
The capability of document types such as HTML to evolve without breaking backwards- or forwards-compatibility
The ability of resources to add support for new content types as they are defined without dropping or reducing support for older content types.
One benefit that's obvious with regards to web based applications is that a RESTful implementation allows a user to bookmark specific "queries" (or requests) and allows those to be conveyed to others across e-mail, instant messages, or to be injected into wikis, etc. Thus this "representation" of a path or entry point into an application state becomes highly portable.
- Not clear as to being benefits when compared with what, for what purpose. Someone has tried to clarify in italics above, but this is too soon in the article. Who's trying to 'sell' us something here? There's nothing to buy, it's a design principle. Totally uncited. Every point could be counter-argued. No purpose.
Some "RESTful" services will extend the POST method to include the operations of updating and deleting by including additional arguments (e.g. method=delete,method=update). However, in doing so the service is moving the "operation" out of HTTP and inside the request data (similar to a RPC style or SOAP web service).
- Well, if they do, then they're not really REST, are they? We're back to the two meanings again - one for those who get it and one to include all those who don't. So they can say they're RESTful too, cos it's a cool buzzword?
HTTP separates the notions of a web server and a web browser. This allows the implementation of each to vary from the other based on the client-server principle. When used RESTfully, HTTP is stateless. Each message contains all the information necessary to understand the request when combined with state at the resource. As a result, neither the client nor the server needs to remember any communication state between messages. Any state retained by the server must be modeled as a resource.
- I have never read a longer definition of stateless. And it's all pointless because the state of the client is altered by a GET, and PUT, POST etc all alter the server's state. It's the network that's stateless. HTTP, which this refers to, is hyperlinked anyway. And who says how the server MUST model its state? (uncited)
HTTP provides mechanisms to control caching, and permits a conversation between web browser and web cache to occur using the same mechanisms as between web browser and web server. No layer can access any conversation other than the one it is immediately involved with.
- Again, getting started for the most detailed definition of caching, but there's no need because that's HTTP and the internet, not REST, and so discussed elsewhere and makes no difference here.
For this reason some "RESTful" services will overload the POST method to make it perform the operation updating (PUT) and deleting (DELETE) a resource.
- again, so they're not really RESTful, are they?
The statements below refer to REST in the context of Web Services, specifically as opposed to SOAP. Note that Fielding's dissertation presents REST in the context of information and media access, not web services. It does not contrast REST to RPC, although it does contrast RPC to HTTP (which is used to illustrate an implementation of REST).
REST
Resources—Commands are defined in simple terms: resources to be retrieved, stored / get, set—difficult to do many joins
RPC
Commands—Commands are defined in methods with varying complexity: depending on "standard"—easier to hide complex things behind a method
REST
Nouns—Exchanging resources and concepts
RPC
Verbs—Exchanging methods
REST Triangle of nouns, verbs, and content types.
A RESTful web application requires a different design approach from an RPC application.
An RPC application is exposed as one or more network objects, each with an often unique set of functions which can be invoked. Before a client communicates with the application it must have knowledge of the object identity in order to locate it and must also have knowledge of the object type in order to communicate with it.
RESTful design constrains the aspects of a resource which define its interface (the verbs and content types). This leads to the definition of fewer types on the network than an RPC-based application but more resource identifiers (nouns). REST design seeks to define a set of resources with which clients can interact uniformly, and to provide hyperlinks between resources which clients can navigate without requiring knowledge of the whole resource set. Server-provided forms can also be used in a RESTful environment to describe how clients should construct a URL in order to navigate to a particular resource.
- This is almost incomprehensible. The only useful bit was 'A RESTful web application requires a different design approach from an RPC application', so I put that back. What do the brackets mean in that diagram? Where's the discussion of MIME as an equal partner? Any references for any of this???
Uniform interfaces in REST and RPC
The uniform interface allows clients to access data from a range of resources without special code to deal with each one, so long as it is actually uniform. The content returned from a user resource could be the globally standard and RESTful HTML, a less RESTful industry standard representation such as UserML, or an unRESTful application-specific data format. Which content is returned can be negotiated at request time. The content could even be a combination of these representations: HTML can be marked up with microformats which have general or industry-specific appeal, and these microformats can be extended with application-specific information.
Uniform interfaces reduce the cost of client software by ensuring it is only written once, rather than once per application it has to deal with. Both REST and RPC designs may try to maximise the uniformity of the interface they expose by conforming to industry or global standards. In the RPC model these standards are primarily in the form of standard type definitions and standard choreography. In REST it is primarily the choice of standard content types and verbs which controls uniformity.
- Another baffling subsection. It's very prescriptive - apparently now even the returned format can make it non-REST and only HTML is really acceptable. Whatever happened to XML and JSON discussed positively earlier (and of course OK)? And does this author really expect to only ever write one REST client and use it over and over for the rest of his life? Not real. Not cited. Made up.
Other interfaces that use HTTP to tunnel function calls or which offer a "POX/HTTP" (Plain Old XML over HTTP) endpoint are also sometimes referred to as "REST" interfaces.<<Fact!date-April 2008>>
- back to confusing the issue again, saying we're all RESTful now, just different kinds of REST!
Various weasel phrases such as "Proponents of REST argue that ..." have also been culled.
The 'Example' subsection was simplified. There was no reason to duplicate all the example code for 'location' if it wasn't referred to in the explanation
I left the following in, in the hope that someone really is going to come back and expand it:
Many of these uniform interfaces follow document-oriented REST patterns rather than object-oriented patterns [should expand on and thus clarify this distinction]:
I left all the non-web stuff alone too. My specialism is the web, so I'm not really the one to comment on that.
I took the 'Confusing' tag off, in the hope that this was the bulk of the stuff that was throwing people off as they read the article. I hope that we can now hone what's left into something more readable and that better covers the real territory, without wandering aimlessly off down so may blind alleys.
The application does, however, need to understand the format of the information (representation) returned, which is typically an HTML, XML or JSON document of some kind, although it may be an image, plain text, or any other content.
Just understanding HTML or JSON etc. is not enough - the API needs to specify how to interpret the fields and content that is part of the hypertext, so that the client can navigate resources via hypertext. —Preceding unsigned comment added by 170.171.10.30 (talk) 16:53, 30 July 2009 (UTC)
Too much removal??
I removed a lot of, what I considered to be, misleading and confusing stuff from this article recently, and detailed the removals carefully above. While I've been away, it seems that user 170.171.10.30 has removed a great deal more, with very little comment, apart from the many edit summaries. And then user FuzzyBSc has added his/her own brand new essay to pad it back out (with the only references being to "Roy said x" primary-source bulletin boards).
I think we may have gone too far. The article is now very heavy reading, it now reads more like a PhD thesis itself, I fear. Much of the removal seems to have been on the basis that "This is about HTTP, REST is not HTTP" and so it goes. But the replacement essay seems to be all about HTTP, but without mentioning it, or any examples. It is also without any discussion or viewpoints other than those of our friend Roy, unmitigated by any
recognisable reference to reality.
The simplest way to put my worries is to say that it is fundamental to WP:RS that we should not depend on primary sources (e.g. Fielding's PhD thesis and his personal comments on it from internet chat) but on secondary sources like what other academics and practitioners, text-book writers and respected commentators have made of what he said. I think we were closer to that with this article at some point in the recent past, i.e. about here, although I agree that the 'Outside the Web' stuff should go, and the examples may be better labelled as such and as no more than examples.
I'd started to revert one of those "HTTP is not REST" edits, before wavering and canceling the revert. While I can appreciate the sentiment, it's important to acknowledge HTTP as being highly interrelated with the development of REST, as well as being the most well known/biggest concrete implementation of REST. I guess I ultimately canceled my revert because I used 'pedagogy' while describing my reasoning, and realize that [[Wikipedia::NOTTEXTBOOK]]. At the same time, a little concreteness via HTTP could go a long way to making the page comprehensible to readers.
I'd agree the User:FuzzyBSc additions have some problems, primarily the whole "rest state" nonsense. At the same time, in there lies a pretty good procedural description of the concept of REST. jsled (talk) 23:17, 11 August 2009 (UTC)
(Whooops! Sorry about the formatting. "It's All Text" and wikipedia-mode seem to have conspired against me, there. :) jsled (talk) 15:10, 12 August 2009 (UTC)
HTTP is the primary protocol used in REST implementations, but HTTP itself is not inherently REST. The REST specification does not mention HTTP anywhere, but I agree it's worth discussing in this article. But too much of the previous content focused on misleading or irrelevant things like how to assemble URIs, which is a detail of HTTP - the only thing REST requires of URIs is that they are opaque (not as suggested in removed content, which seemed to imply that hierarchically structured URIs are part of REST). Proper usage of HTTP verbs like GET and POST are necessary for REST when using HTTP, but the removed content suggested that these verbs must map to CRUD-like actions, which is totally inaccurate and misleading.
If you want to see a great example of a properly RESTful HTTP-based service, look at Sun's cloud API: http://kenai.com/projects/suncloudapis/pages/Home It is largely a description of its various media types, which a REST API should be. It's the best example I've seen of REST, with excellent documentation. Maybe this could help to understand how to give some implementation example in this article. CRUD operations based on hard-coded URIs is definitely not what REST is about.
As REST is now a trendy buzzword, we should be careful how we write this article. People love to label their services REST based on a thousand different misguided interpretations ("REST means simple and clean", "REST means CRUD", "REST means pretty URIs" etc) when REST is actually an architecture with very specific constraints.
Also regarding WP:RS: Fielding is appropriate to cite here, and I agree with the need for more third party sources, but I think that most of the removed content did not rely on reliable sources (though lacking citations), but rather unreliable ideas of what REST is based on Wikipedia editors' own interpretations, which is against WP:RS. I'd love to see reliable source citations for some of the removed content, as I'm willing to guess they don't exist outside of misguided blog posts and so on. There's an absolute wealth of misinterpretations of REST out there online, so let's not let that overwhelm the information minority from reliable sources.
170.171.10.30 (talk) 16:37, 13 August 2009 (UTC)
Missing Vinoski reference
Some material citing Steve Vinoski was recently commented out, due to lack of references. While I don't know if we want to keep all of the content, I googled the first quote ("Imagine, for example, that the web...") and found this:
Steve Vinoski, "REST Eye for the SOA Guy," IEEE Internet Computing, vol. 11, no. 1, pp. 82-84, Jan./Feb. 2007, doi:10.1109/MIC.2007.22
CRUD mapping: (PUT,POST) ≟ (CREATE,UPDATE) or ≟ (UPDATE,CREATE)
People keep swapping PUT/POST in relation to the CRUD semantics. The most appropriate mapping is POST=CREATE, PUT=UPDATE…
From RFC 2616, re:POST:
POST is designed to allow a uniform method to cover the following functions:
Annotation of existing resources;
Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
[…]
Extending a database through an append operation."[1]
Note that "annotation" is not necessarily updating existing resources, but creation annotations of those resource.
From RFC 2616 for PUT:
"In contrast [with POST], the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource."[2]
Though there's not a 100% equivalent mapping, and while PUT can explicitly be used to CREATE a resource, the most appropriate mapping is POST=create subordinate resource and PUT=update existing resource.
216.114.130.196 (talk) 16:52, 7 January 2009 (UTC)
I don't understand how you can say that. You point out the first flaw yourself in saying that PUT can create, but a bigger one is in the idea that POST has something to do with creation of resources. There is absolutely nothing to suggest that this is what any POST will do. It can do creation operations (or indeed, updates, deletions or act as an inefficient GET) or it can do something that doesn't fit into the CRUD mapping at all. In CRUD you CREATE at a particular place, if you want to do that in HTTP you use PUT.
The only time POST is most appropriate for creation is when the handler will decide what and where something gets created. This does not map to CRUD. It does map better to CRUDE with POST being the EXECUTE of CRUDE. To the extent that the analogy is useful, I'd put it there, though I don't think the analogy is so useful as to make dwelling on it profitable.
Why do you remove the item from the text you quoted which doesn't fit your argument, rather than just see it as already refuting it? Why do you say 'Note that "annotation" is not necessarily updating existing resources, but creation annotations of those resource.' when there is nothing to indicate whether it is an update or a creation - it could well be either or something else besides. Talliesin (talk) 09:34, 18 September 2009 (UTC)
I was 216.114.130.196 at the time. I suppose I was going for a rough, "best-fit" mapping of the HTTP methods to "CRUD", without footnotes, parentheticals, qualifications or changing the acronym. I acknowledge that PUT can be used for creating, and POST covers other functions; there is the long-standing POST(p[rocess]) and POST(a[ppend]) distinction. But if we're just trying to allocate the core HTTP methods to CRUD initials one-to-one, I think the most appropriate mapping is POST=CREATE (similar to INSERT with an auto-increment primary-key column) and PUT=UPDATE.
Maybe the best thing for the text is to say there is no clear mapping, since both POST and PUT are defined in terms of both creating and updating resources (and doing even more, potentially, in the case of POST). jsled (talk) 14:37, 18 September 2009 (UTC)
User 170.171.10.30 recently removed all references to HTTP, including the little table we used to have mapping HTTP verbs to CRUD actions. I admit I wasn't too chuffed at the time (see #Too much removal?? below) but actually we snuck a few bits back in, wrote some new stuff, tweaked here and there, and I think the article really is better after the purge. One of the bits someone snuck back in (not me) is the table at Representational State Transfer#RESTful web services, which I think is worth a read. The way I understand it is this: POST to a collection URI creates a record in that collection; PUT to a non-existent item URI creates that item; PUT to a current item URI updates that item. Other combinations are possible, but their usefulness is generally less clear. As far as the article is concerned, I think these points are well covered in that table, and as we're trying to minimise the binding between the bulk of the article and HTTP, I think that's enough. In other words, I don't think we need any new coverage of the points you've been debating here. Having looked at the table, do you agree? --Nigelj (talk) 16:08, 18 September 2009 (UTC)
1) Decide on an unambiguous definition of REST. IMHO, Fielding lost and the engineers won. REST = XML over HTTP, and it has a particularly important role as a vastly simpler alternative to SOAP.
Fielding *defined* REST in his thesis. While the term has been misappropriated to talk about XML over HTTP, that's no justification for making the REST article about it. I'd be supportive of making that distinction clear very early in the article, but not removing the distinction altogether.
What hype are you referring to that should be removed? Honest question.
I'd agree this article could use some significant cleanup. :/
There are plenty of examples of RESTful services which do not use XML. JSON and and YAML are other very common data types in use Nicholsr (talk) 00:28, 16 January 2009 (UTC)
It should not be Wikipedia's role to judge what should be called REST, who is right or who should own the term. If there are two widespread different but conflicting ideas about REST is, or two different practices calling themselves REST (i.e., Fielding's definition vs. the XML over HTTP camp) then this article should describe those two camps / definitions, their origins and differences.--Ericjs (talk) 20:59, 12 February 2010 (UTC)
Statelessness
The section on statelessness is partially incorrect. Session-based cookies meet the criteria as currently defined, but they are not considered stateless or RESTful. Alternately, if you take the definition very strictly to exclude cookie sessions, then no serious applications can be RESTful. The statelessness criterion is actually that all context associated with a request is either embedded in the request payload or if not carried in the payload they are named by URLs. Cookie session values are not nameable by URI, and all the session values are not included in each request, thus they are not stateless. --Naasking (talk) 20:29, 29 April 2010 (UTC)
Our article says, "no client context being stored on the server between requests". Fielding's dissertation[7] says, "the client-stateless-server (CSS) style ... cannot take advantage of any stored context on the server". I don't see a problem. Cookie data is stored on the client, and is sent to the server with every request during the session (or the lifetime of the cookie). Nothing is stored on the server related to the state of every client. Are you muddling "Session-based cookies" and "cookie sessions" in some way that is defined by whatever proprietary web development environment it is that you are used to? Regarding URLs, almost anything that can be stored in a cookie (and sent with the headers of every request) could be appended to the URL of these requests (or added to the POST data when that verb is used). The resulting URLs would be horrible, but it could be done. It is true that if you store whole database objects in your client's server-side JSP or ASP.NET 'session' variable, or use those environments' built-in session-based logon and credential management stuff, then you have not built a RESTful system. --Nigelj (talk) 21:00, 29 April 2010 (UTC)
By "session-based cookies" I meant an ASP.NET-style session pattern, yes. Any use of such a session is not RESTful, nor is the use of any similar context that is not addressed by URL or provided inline. My point is, the description used by Fielding and in the wiki page is too easy to misinterpret. "cannot take advantage of any stored context" implies there cannot be server-side state. Of course this isn't true, because a lack of server-side state is impossible for any meaningful application, and so everyone misinterprets this phrasing in their own way leading to much confusion. What was meant is that all such server-side state must be addressable by URL. I think this sort of phrasing would clarify the intent, and further clarifies how REST is a composition of simple messaging and addressing primitives. --Naasking (talk) 03:43, 30 April 2010 (UTC)
It is true that you can't build a RESTful system if you make free use of use all the Microsoft stuff that comes with ASP.NET. That does not mean that you can't build "any meaningful application" RESTfully - just look at what the Ruby guys are doing, for example. REST is Representational State Transfer, and so sometimes state is transferred (by e.g. POST, PUT, DELETE) to the server and the server's state is changed. So it is possible to have a database and to have clients alter it. What breaks the REST architecture, for example, is if you have an HttpContext.Session object on the server for each logged-on user and in it you save all kinds of details about the specific user's state - authenticated, admin-user, 12 days until his password expires, will be logged off in 14 minutes if he doesn't do something before then, likely to request this, that, and the other database records again soon, so we have them cached in session for him, etc, etc. That is a practical meaning of the words "no client context being stored on the server between requests" in the article. If you do all those things for each client, your application will not scale beyond a certain number of concurrent users - that's bad design, but it's built into ASP.NET unless you go to lengths to prevent it being used. It's OK for an intranet app, but then that's ASP.NET for you, IMHO. --Nigelj (talk) 23:04, 30 April 2010 (UTC)
You're not really addressing my point regarding the wording on the wiki page. All that context you list would conform to the REST model if it were addressable by URL and thus conformed to URL semantics/lifecycle/etc., or if it were passed explicitly in each request. This is not clear given the current wording in "statelessness". --Naasking (talk) 16:10, 3 May 2010 (UTC)
More concrete information on RESTFul web services
I believe that people will come to this article seeking a concrete understanding of RESTFul web services. There is a lot of practical and concrete material in Leonard Richardson and Sam Ruby's Book which I added to the references in the article.
I see this has now been implemented in the article in an altered form. In particular PUT and POST seem to be the wrong way round. I'm going to fix that now as I'm pretty sure that it is wrong unless I'm going mad. Oligomous (talk) 17:51, 12 May 2010 (UTC)
Oligomous - You must be going mad. ;) I'm pretty sure the POST and PUT definitions were correct, and you swapped them. I don't have my copy of RESTful Web Services handy to verify, but this answer on stack overflow verifies. Keithjgrant (talk) 22:50, 13 May 2010 (UTC)
Addition: I found the following articles helpful from a practitioner's point of view:
REST and the Real World by Paul Prescod (February 20, 2002) -- addresses several requirements for web services with REST
Methods by themselves are not idempotent. It is very common for people to use GET to do all sorts of non-safe things. By declaring a method as idempotent, you basically telling your users that calling the method repeatedly would give them the same result. So, what counts is the semantics implied with each method that counts. Back to PUT and POST, the only essential difference is that PUT should be idempotent while POST is not. However, not all updates are idempotent. If you use PUT for such situation, a user would wrongly assume that repeated PUTs would give them the same result but in fact it is not. In situation like this, POST should be used because it conveys the correct semantics.— Preceding unsigned comment added by 124.178.228.149 (talk • contribs) 00:53, 26 November 2010
Yes, that's the point of REST - not to redefine what HTTP methods are for. In a RESTful interface, all PUT actions must be idempotent and POSTs are not. People have been defining GET and POST to do whatever they like in web applications and RPC web services for years, and the point of REST is that we look up how the existing HTTP methods are defined and use them only as defined. If the developer feels free to decide whether a PUT or a POST is going to be idempotent or not, s/he is not designing a RESTful interface (which is what the article is about). --Nigelj (talk) 15:52, 26 November 2010 (UTC) P.S. Copied from my talk page in case others wish to comment too.
