Talk:Representational State Transfer

From Wikipedia, the free encyclopedia

Contents 1 A disclaimer 2 REST without XML 3 REST is an architectural style for distributed hypermedia systems 4 I do not get it 5 Discovery 6 See Also 7 A simple explanation 8 stateless client/server protocol principle 9 REST frameworks 10 REST and web browsers 11 HTTP verb relationship to cut-and-paste 12 REST on SOAP 13 Major revision of article, wanting expansion 14 Examples of REST 15 Introduction error 16 Major reversion of article 17 suggested change to resource example 18 More Practical 19 Suggested Organization Changes 20 WSDL 2.0 21 Validity of "RESTafarians" 22 Negotiated Content Type; State Examples; Authentication 23 Problems with the REST v RPC examples 24 Both RPC and REST articles needs to acknowledge inherited software design ideas that are independent of REST or RPC

[edit] A disclaimer

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)

[edit] 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.

Lost Goblin

I compltely agree. REST has nothing to do with XML.--194.221.74.7 07:51, 26 July 2006 (UTC)

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 Nord 2006-07-26 20:44Z

Agreed. In 'real life', the resource representation can be JSON too, for example.EduardoPadoan —Preceding comment was added at 14:55, 14 March 2008 (UTC)

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. Goflow6206 04:33, 9 January 2007 (UTC)goflow6206

[edit] 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 what RTF 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)

[edit] I do not get it

Read the article but I fail to understand what REST is. This document needs some work!--seweso 12:21, 25 November 2005 (UTC)

Agreed. I think a simple definition in the beginning would help, then an in depth explanation after the ToC 67.165.127.123 04:19, 17 July 2007 (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.

--Zybez (talk) 23:33, 9 April 2008 (UTC)

[edit] 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.

203.173.154.4 08:09, 9 January 2006 (UTC)

[edit] See Also

See also
# 9P, Plan 9 from Bell Labs and Inferno

Why? What has "Plan 9" got to do with REST? 68.156.53.188 15:26, 9 January 2006 (UTC)

See [1], there are many similiarities between REST and the use of file systems in Plan 9 Lost Goblin 19:03, 31 January 2006 (UTC)

[edit] A simple explanation

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.

Everything else in REST is just commentary or implementation details. --Randyjg2 23:33, 28 February 2006 (UTC)

[edit] stateless client/server protocol principle

This section has the following appended:

(some of those practices, like URL-rewriting, are not RESTful).

I do not see what URL-rewriting has to do with state at all. -- Jon Dowland 13:48, 16 June 2006 (UTC)

Good point

[edit] 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 : JSR 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

[edit] REST and web browsers

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.Juanjobnt 07: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

[edit] 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?"

See also my MinimumMethods piece on restwiki, and my earliest blog entry mentioning this analogy. There may be earlier and more diverse sources for this analogy. The only one on my radar at the moment is this nod by Stefan Tilkov.

[edit] REST on SOAP

"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."

Is the "HTTP without ... SOAP" still appropriate? REST principles are being applied to Web Services, i.e. SOAP. John Vandenberg 07:49, 2 October 2006 (UTC)

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. --Shepard 17:59, 10 July 2007 (UTC)

[edit] Major revision of article, wanting expansion

I have authored a major revision to the main article (Representational State Transfer), keeping a few points and links. Yes, the first request for expansion is about the lead. Please add to the substance of the article. Concision is golden. Links are golden. —Etan Wexler 20:17, 21 October 2006 (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:

http://en.wikipedia.org/wiki/Talk:Representational_State_Transfer#Suggested_Organization_Changes

Informedbanker 16:54, 5 May 2007 (UTC) 12:54 2007 May 5

[edit] Examples of REST

Are there examples of REST? Should there be a section for example?

• Amazon
• Flickr
• Google
• YouTube[2]

--Dan 20:56, 23 October 2006 (UTC)

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.

See [3] and [4] for examples.

Thanks! - Dan

Dan --Dan 21:18, 23 October 2006 (UTC)

REST is a style of software architecture. There are architectures which follow REST. The modern Web is an architecture which largely follows REST. The main article has a section devoted to the Web as an example of architectures which follow REST. The main article has a section devoted to examples of architectures which follow REST and which are not the Web. If you want to enhance the latter section, I welcome your additions. I cannot discern quite what you want that is not already in the article. Do you want a section with the word “examples” in the title?

—Etan Wexler 14:44, 24 October 2006 (UTC)

we can talk about REST-over-HTTP, then some specific examples (and tools) -linking to stuff in wikipedia like Amazon S3. SteveLoughran (talk) 15:32, 10 April 2008 (UTC)

[edit] Introduction error

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

source

Benjamin Carlyle -- Mon Oct 23 21:31:34 UTC 2006

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.

Here is an example of a more "practical" definition from http://www.petefreitag.com/item/431.cfm

What is a REST Web Service

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.

Dan--Dan 14:16, 24 October 2006 (UTC)

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.

—Etan Wexler 15:30, 24 October 2006 (UTC)

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. -- Felipec 13:18, 15 April 2007 (UTC)

[edit] Major reversion of article

An anonymous contributor (see Special:Contributions/155.212.59.41, User_talk:155.212.59.41) restored a version that the contributor found “much more intelligently written and useful”.

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.

—Etan Wexler 21:46, 26 October 2006 (UTC)

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?

—Benjamin Carlyle Sun Oct 29 21:54:31 UTC 2006

[edit] suggested change to resource example

Instead of the following two resources in the example

http://example.com/findUserForm
http://example.com/findLocationForm

would the following not be a better implementation:

http://example.com/forms/find/Users/
http://example.com/forms/find/Locations/

This has the following benefits:

• 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:

http://example.com/users/
http://example.com/locations/

--Kgaughan 12:39, 2 March 2007 (UTC)

That would be a list of users/locations to me, rather than a form for finding users/locations. --Shepard 18: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 URI construction. --Kgaughan 13: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. --Kgaughan 13:50, 27 August 2007 (UTC)

[edit] 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.

• User:Felipec/Representational_State_Transfer

-- Felipec 14:23, 15 April 2007 (UTC)

[edit] Suggested Organization Changes

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

-- User:informedbanker 10:23 2007 May 4

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 of section 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:

http://www.docunext.com/resources/blog/2007/05/05/fieldings-dissertation/

-- Informedbanker 16:49, 5 May 2007 (UTC) User:informedbanker 12:48 2007 May 5

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. -- Felipec 12:39, 1 July 2007 (UTC)

[edit] 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. —Preceding unsigned comment added by 151.16.215.179 (talk) 23:49, 17 September 2007 (UTC)

[edit] Validity of "RESTafarians"

zealous REST advocates call themselves RESTafarians. Is this a joke? —Preceding unsigned comment added by 65.95.32.53 (talk) 19:45, 12 November 2007 (UTC)

No joke, the term has substantial usage in various fora. jsled (talk) 19:04, 20 November 2007 (UTC)

[edit] 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 in http://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.

3. Lastly, I would like to see some discussion on handling authentication in a RESTful application. —Preceding unsigned comment added by Kymike (talk • contribs) 06:01, 12 December 2007 (UTC)

[edit] Problems with the REST v RPC examples

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)

[edit] 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)