[bobfromhuddle]

It's really not, I'm sorry.

State is carried by the client, the client traverses links to find out what it can do, the responses are described by a published content type, and the content type defines the semantics of the protocol.

It's not hard, but people like to pretend that it is. Nothing says you can't stick to GET and POST, nothing requires weird headers.

"ReST in Practice" is a great introduction for engineers.

[jcrites]

A person looking to understand "What is REST? What is a RESTful application?" would be well-served by considering websites rather than web services.

Facebook, Amazon, and Hacker News are good examples of RESTful applications. You can enter them through their website roots with no prior knowledge beyond standard web media types like HTML/CSS. The site roots display some information, expose some functionality like search, and link to pages with more capabilities like to create an account. The search function is expressed as an HTML form, and when the user submits their search, the HTML spec tells the browser to navigate to a new URL composed from the search form fields. The search result page displays a list of hyperlinks to other resources, such as products on Amazon or people on Facebook. Navigating to those pages lets you discover information and hyperlinks to other resources such as a person's photos, related products, etc.

The way a browser navigates through a website by following links is the classic example of a RESTful application, and is the meaning of "hypermedia as the engine of application state". Fielding also wrote a blog post clarifying REST and its constraints: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

> A REST API should be entered with no prior knowledge beyond the initial URI and set of standardized media types that are appropriate for the intended audience. A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). A REST API should never have “typed” resources that are significant to the client. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type

Some confusion about REST seems to stem from misguided attempts to apply REST to scenarios for which it's not a good fit - scenarios where there is by necessity tight coupling in the form of mutual knowledge of specific data types and operations. Other confusion about the term "REST" comes from applying subset of its principles, resulting in a popular label that refers to a large spectrum of architectural styles. The Richardson Maturity Model helps organize these functionality subsets into levels that can be named and considered separately - services termed REST are sometimes level 1 or 2 in the Richardson model.

http://martinfowler.com/articles/richardsonMaturityModel.htm...

[stanleydrew]

Exactly. The problem is that, for some reason, people decided that an "API" should be "RESTful". Ruby on Rails put this idea into a lot of developers' heads.

An API is probably the worst thing to try to make truly RESTful, in the full HATEOAS sense.

Further confusion comes from the fact that some of the REST constraints are actually very useful in machine-to-machine API design. Thinking about a system in terms of a large number of resources operated on by a standard set of verbs is nice. Caching is nice. The un-bloating of HTTP bodies from the SOAP days is nice.

I think there is some consensus that we can call that thing an "HTTP API" rather than a "REST API", which might start to clear up some of the confusion.

[wstrange]

Sorry - the whole "REST is just like websites" thing drives me nuts.

With the web, it is not the browser doing the navigation; It is very advanced AI wetware.

It is hard to find widespread examples of machine to machine interaction based purely on RESTful discovery.

I think REST is interesting - but at the end of the day, is it really all that different from other communication mechanisms?

[stanleydrew]

But REST is just like websites. It's a term that was literally coined to describe the web, including websites and browsers.

Why does it drive you nuts?

[sopooneo]

For me, it drives me nuts because zealots do a lot of handwaving to get from "the web itself is RESTful!" to "and it's the best possible way to build an API".

[jcrites]

People who are interested in this topic - what REST is and is not, what it's meant to be, and so on would do well to read Fielding's thesis in full [1]. There is quite a lot of misunderstanding of the topic.

REST as a concept was created as a way of characterizing a successful architectural style seen in web applications, a common set of constraints and advantages realized from those constraints. REST is attempting to characterize the architecture of the web, so I think it would be accurate to say "the web itself is RESTful":

> The first three chapters of this dissertation define a framework for understanding software architecture via architectural styles, revealing how styles can be used to guide the architectural design of network-based application software. Common architectural styles are surveyed and classified according to the architectural properties they induce when applied to an architecture for network-based hypermedia. This classification is used to identify a set of architectural constraints that could be used to improve the architecture of the early World Wide Web.

> Architecting the Web requires an understanding of its requirements, as we shall discuss in Chapter 4. The Web is intended to be an Internet-scale distributed hypermedia system, which means considerably more than just geographical dispersion. The Internet is about interconnecting information networks across organizational boundaries. Suppliers of information services must be able to cope with the demands of anarchic scalability and the independent deployment of software components. Distributed hypermedia provides a uniform means of accessing services through the embedding of action controls within the presentation of information retrieved from remote sites. An architecture for the Web must therefore be designed with the context of communicating large-grain data objects across high-latency networks and multiple trust boundaries.

> Chapter 5 introduces and elaborates the Representational State Transfer (REST) architectural style for distributed hypermedia systems. REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems. [...]

> Over the past six years, the REST architectural style has been used to guide the design and development of the architecture for the modern Web, as presented in Chapter 6. This work was done in conjunction with my authoring of the Internet standards for the Hypertext Transfer Protocol (HTTP) and Uniform Resource Identifiers (URI), the two specifications that define the generic interface used by all component interactions on the Web.

(To be clear, I'm not intending to comment on whether REST is good or bad, nor its suitability to a purpose like API design. I just mean to comment on what it factually is and is intended to be, since from my perspective it frequently seems to be misunderstood.)

[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/introduc...

[jholman]

Which part of logins and cookies is RESTful?

Fielding's REST requires that the protocol be "stateless"... not that there be no state, but that the client and the server need not keep track of each other. Cookies, as Fielding explicitly calls out, are in violation of this principle. Every website that uses cookies is not RESTful.

Some people might conclude from this that FB, Amazon, and HN are "not good", because they're not RESTful. I personally conclude something else, but YMMV.

[adam419]

The RESTful principle actually just declares that request response cycles and server-client interactions don't have to be stateful, not that it's necessary they're stateless.

It's still possible to use sessions and other ways of maintaining client state while adhering to other stateless principles such as indempotency of certains types of requests.

[colin_jack]

I don't really think that's always true, if the cookie merely has a session ID then the session itself can be stored server-side (not necessarily in memory of course) and in fact could be a resource in its own right.

Also deciding to put the session ID in a cookie not the URL is purely a pragmatic approach (e.g for security reasons).

[swax]

Even if REST was a standard and no one ever argued about it, I still wouldn't use it. It is needless overhead designed by a PhD to solve problems I haven't encountered for 15 years. API traversal sounds nice, but who uses it? Has the benefit been realized or is it still just theory? With a simple JSON RPC API I can still transmit objects representing state. Like you said it's not complicated. Has it crossed your mind that REST is maybe more trouble than it's worth?

[bobfromhuddle]

The same arguments were made about object orientation: I've never needed it, it's useless baggage with no real world benefits, it sounds great in theory but has no practical use...

I've built hypertext APIs, and they worked really well.

We had a(n overly) complex domain model where most of the complexity was around managing a permissions model for access to resources. We tried a whole bunch of ways to represent the actions available to end users, but the only one that worked really well was to advertise a URI when you could do something, and to omit it when you couldn't.

All the nightmarish logic was safely hidden behind the uniform interface. Clients only needed to know that they should follow links, and that the absence of a link meant that a resource wasn't available to them because reasons. It was a beautifully natural mapping of a difficult problem domain into a simple consumption model.

As a bonus, we could change URI structures around when we felt like it, and our clients never missed a beat, because they always followed links from a well-known entry point.

It's not always the right choice, there is plenty of room for simple RPC, but for workflows, and dynamic discovery of resources ReST works a treat.

[picozeta]

> The same arguments were made about object orientation: I've never needed it, it's useless baggage with no real world benefits, it sounds great in theory but has no practical use...

And haven't this people been right? :)

It was (and still is, but people are fortunately more skeptic) completely oversold like REST now.

[isolate]

For me the oversold part about OO is inheritance and design patterns. I find classes plus composition are really natural and helpful for a lot of problems.