Hacker News new | comments | ask | show | jobs | submit login
What RESTful actually means (recurse.com)
233 points by luu on Dec 20, 2015 | hide | past | web | favorite | 133 comments

REST is the definition of a buzzword. Vague. Useless. Everyone talks about it, but no one ever 'understands' it. You make your API REST not because you think it's good, but because everyone else does it. It's instant karma. Like XML was 10 years ago. Who cares if you have to make a lot of ugly confusing endpoints - at least you can call your API RESTful.

I like how Dropbox bucked the trend and went with a simple POST based API. JSON parameters in. JSON response out. No complicated urls, strange headers, verbs, hateoas, etc..


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.

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.


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.

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?

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?

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

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

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.

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.

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

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?

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.

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

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.

REST is one of those things were if you don't implement all of it, you won't really reap the benefits of all those architectural constraints combined. In your Dropbox example, any client will be bound to the Dropbox API. Consequently, Dropbox are now bound to each and everyone of those clients; they cannot make changes on the server side without breaking every client. This is what REST aims to provide - a safe way for the server to change as needed without breaking clients.

Imagine if Dropbox registered a set of mime-types for each of the different resource representations. Those mime-type RFCs would describe how clients interpret the representations whilst simutainiously giving Dropbox the ability to change the server as they need without fear of breaking clients.

This would be because clients would be foxing on how to process the media-types, not the API. The various interactions a client can make with a representation (regardless of the URL it came from) would be bound to the media-type e.g. rel-types for edit, upload, create etc which the RFC would describe the appropriate HTTP interactions e.g. POST a media-type of x to the url at rel-type "edit".

However, I think the real reason that REST hasn't been adopted fully is that service providers like Dropbox have found that there advantages to binding client developers to their hardcoded APIs; the last thing Dropbox wants (and what REST would provide) is a standardised set of media-types and RFCs describing the interactions for a standardised way of interacting with an external cloud-based storage provider.

It's just another form of lock-in, and reminded the cynic in me of the bad old days of MS Office document lock-in.

umm, can you cite a RESTful cloud storage API that's consistently implemented between providers? If Dropbox's API was RESTful would that save me any time using Google's competing API? By the way, all these platform provide SDKs for you anyway and that's usually a better way to use them.

When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities. REST or not building a client for one doesn't really make you closer to using another. Also Dropbox's old API was REST and it doesn't seem more portable (https://www.dropbox.com/developers-v1/core/docs)

> can you cite a RESTful cloud storage API that's consistently implemented between providers?

It's been a while since I've worked with it, but IIRC, WebDAV is one example.

> Dropbox's old API was REST

That's not REST. It's that weird anti-REST where people define URI patterns instead of media types. I don't know why it became trendy to label things like that REST, but they aren't.

If Dropbox's API was RESTful would that save me any time using Google's competing API?

If Dropbox's API was RESTful, you'd be able to use Google by only switching the initial URL - which could even be configurable by the user, or auto-discovered from the website.

When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities.

They don't vary _widely_ in concepts and capabilities, they add a layer on top of the same concepts (files, directories, upload/download, get public URL), and REST allows you to support generic and specific clients easily, by either using extensible or multiple media types.

Also Dropbox's old API was REST and it doesn't seem more portable

It resembled REST, but it wasn't. A good way to tell: if you need a documentation page with a list of all the URLs you can call, it's probably not RESTful.

The claim "just change the base URL and everything works" always seemed unrealistic to me. The relation names, the understood data-types, ... still have to be compatible, and IMHO that is the point where things would fail.

Those are the media types, which should be standard or at least reusable by others. The difficulty is not technical, it's economics: everyone wants to lock in their users, and this goes against that wish.

When the conditions are right, you do see this: RSS/Atom is a good example.

It is technical.

Show me a general purpose program that can navigate, interpret and comprehend a variety of media types and I will show you an AI.

It navigates the media types it has been programmed to handle. What part of that requires AI?

Why is that that much better than navigating the fixed relative URLs of a non-REST a client has been programmed to try?

Some advantages: https://blogs.oracle.com/craigmcc/entry/why_hateoas

But what I really see as the main advantage is the decoupling of server and UI, kind of like Android Intents on steroids. By using standard formats and dynamic routes between them, the user is no longer tied to a silo with a window through which they can interact with their data; they can know use his own chosen software to handle the different types of information, jumping through them as needed, without ever being locked-in to a particular provider.

And for the developers, why are we building the same crap again and again using the API du-jure, when 90% of it uses the same concepts as existing software? Why do we need thousands of libraries and middleware that provides a "single API to many services"? We spend so much effort building these rickety integrations, just because the providers insist on using different names for the same things.

Doesn't it abhor you, the waste of it all?

The issue is that most vendors don't want to converge on a standard. Stuff would be fine if that standard wasn't properly RESTful, as long as it was a standard, but many arguments towards RESTful IMHO present the benefits we would get from any standard as the benefits we would (only) get from a RESTful standard.

I agree that the current situation is crappy. I agree that HATEOAS/REST ideas implemented properly and with the intend to cooperate would help a lot, and that there are many worse candidates for a standard.

I disagree that HATEOAS/REST would matter that much, compared to the "implemented properly and with the intend to cooperate".

How many APIs (and corresponding clients) do you know where "only switching the initial URL" is enough? I don't know many. Doesn't this require incredibly complex clients?

No, it doesn't require complex clients. There aren't many examples because (1) most developers don't even understand the concept and (2) it reduces lock-in, which most providers aren't interested in supporting.

> No, it doesn't require complex clients

You really don't think that a flexible client which is able to discover resources and actions based only on an initial URL is more complex than one which is more hardcoded to a specific implementation and resources? I must be missing something, because to me, it obviously is.

The obvious example of the Web and web browsers is not entirely convincing to me. Yes, browsers are flexible, but at the same time, the Web is an incredibly specific example. There are "hardcoded" expectations of what a web browser must be able to do, that I simply don't see in more general examples and use cases. And whenever we want to do something out of the ordinary with a web browser (I know, I know, "web browsers were never meant for that!") this general model of the web breaks down and we stray into wildly incompatible and hacky ways of doing things.

It's not more complex, it's just different. Constructing URLs is more complex than just following them, for example.

bingo! same thing I said in 2012 https://www.youtube.com/watch?v=Nh6VeuvVRdQ . Depressing that time passes, and nothing really changes.

Webdav predates REST but it essentially ticks all of the boxes that make up REST. Plenty of providers offer Webdav cloud storage (basically all of the smaller ones since they can't really afford to maintain their own API).

It does? The REST thesis came out in 2000, looks like the (and AFAIR) WebDAV came later?



WebDav dates back to 1996. You've just got a list of the latest rfcs.


I wonder why all the larger ones don't support it.

Also the existence of WebDAV doesn't really demonstrate that merely adhering to REST will make your clients portable.

Whilst I can't provide you an example for cloud storage, I can for syndicated feeds. ATOM is an example of multiple clients interacting with separate syndicated feed servers. The individual implementations can all differ.

The way a client interacts with the server is via the media-type and HATEOAS (via the rel-types).

> umm, can you cite a RESTful cloud storage API that's consistently implemented between providers?

WebDAV? You can get pretty far with eg davfs and Plone/Zope -- and you can also mix and match servers and clients. Now, lots of WebDAV clients and servers are broken in many sad ways... but it exists.

> mm, can you cite a RESTful cloud storage API that's consistently implemented between providers

Fielding worked at Day Software, which made a web content management system. They contributed parts of their system to the community as Apache Jackrabbit [1] before getting acquired by Adobe.

Not sure if Day Software's APIs match your asks though.

[1] http://jackrabbit.apache.org/

Not RESTful per se (though certainly not un-RESTful, either) but a number of vendors support a healthy subset of the S3 API such that the vendors may be interchangeable for your application.

> However, I think the real reason that REST hasn't been adopted fully is that service providers like Dropbox have found that there advantages to binding client developers to their hardcoded APIs; the last thing Dropbox wants (and what REST would provide) is a standardised set of media-types and RFCs describing the interactions for a standardised way of interacting with an external cloud-based storage provider.

I'd argue it's not a problem if a vendor can generate clients for his API.

I'd also argue that most clients break with each API version anyway, because of the way developers code them.

I agree that most people just use REST as a buzzword today but don't really know what it is.

As I remember REST was popularized by Rails a few years back. If you go back and look at the railsconf talk by Hansson in 2006 you can see that the Rails people just wanted something that handled CRUD operations. However, one of the drivers behind REST was to provide web services for machine to machine communication - something that was traditionally done by WSDL files in SOAP. The Rails people didn't really have much of a need for HATEOAS, because they were not interested in replacing WSDL files. Primarily they wanted to get away from the 800 pound gorilla that was SOAP services (that back in 2005 was what every Enterprise Java web app was doing). As a result the focus was primarily on PUT/GET/POST/DELETE.

I've seen a lot of "REST" API's that are actually HTTP/RPC API's or quasi-REST API's that mix REST for simple things, but then begin exposing RPC calls as the developers ability to manage complexity breaks down. I've never seen anyone actually using HATEOAS yet (maybe i've been isolated??)

Usually when your boss says "And it has to have a REST API!!" That means that 1. It must use the internet, 2. It must return JSON, 3. It uses URLs to do things. Basically if the above is true it's a RESTful API. I think that most developers actually believe that are making a REST API even when they are not - simply because they don't really know.

Your right about being the new XML buzzword though. 10 years ago if you did web services having WSDL, XSTL, SOAP and XML on a resume meant you were the shiz. Today you have REST and AngularJS on your resume if you do web development. Meh :0

> I've never seen anyone actually using HATEOAS yet

Github AFAIK

> Everyone talks about it, but no one ever 'understands' it.

There are people who understand it to varying degrees. Some who completely understand it and some who don't understand it at all.

So no, it's not a buzzword, it's just a concept.

PS. Dropbox's API requires a lot of hardcoding because of that very switch. Hardcoding that HATEOAS lets you avoid.

"So no, it's not a buzzword, it's just a concept."

I think REST is quite clearly a buzzword. That doesn't mean it's not also a well defined concept; just that it's fashionable to use the term even when that concept doesn't apply very well.

With REST we cannot truly define a degree of understanding. Such a definition would assume that multiple people know and agree on what would be the full extent of that understanding. The problem with REST is not the different amount of knowledge that people possess, but the different ideas that they have about REST. Which is another way to say that REST is not really a well defined protocol. (Have you seen similar vague posts titled "What IMAP4 actually means"?)

Because it is not a well defined protocol, you cannot use the same client library to access random REST APIs. You use/write one library to access Twitter's REST and another to access Facebook's REST. You could argue that you use HTTP in both cases, but that's just the underlying transport protocol - not the API "language" itself. Because of that fact I blame REST for the millions of developers hours wasted in re-implementations of hundreds and thousands versions of the same "concept".

The REST "idea" sure looks sexy when you put it next to an atrocity like SOAP, but that's one of its very few merits.

> Because it is not a well defined protocol, you cannot use the same client library to access random REST APIs.

You misunderstand what REST is. It's not a protocol, it's an architectural style. Of course you can't build one client library to access arbitrary REST APIs – that's like complaining that you can't build an object-oriented library that can be used by any object-oriented language.

REST does, in fact, have a precise definition that is possible to understand and agree on. It's here:


Compare "quantum". Clearly a buzzword in many contexts, even though quantum physics is a legitimate thing.

I've had the "pleasure" of working with big European consortiums where REST is very much a buzzword. I quickly realized that people were using the term as a synonym for "HTTP" for the purpose of making grant proposals and deliverable reports sexier. It's definitely a buzzword!

The chief importance of REST is that for a while it put the emphasis back on the HTTP transport with its associated costs and semantics, and away from the constant attempts to turn everything into an object-oriented remote procedure call.

In my experience hiding the existence of a network behind several layers of abstraction is a really bad idea.

Slack did the same thing which I really like - https://api.slack.com/methods. I was just thinking about JSON RPC style APIs vs 'RESTful APIs.

REST APIs are nice because they follow the data model so closely but there are so many cases in which I am trying to overload something to bend the pattern to my needs. Then again, Stripe seems to have created a fantastic API that handles many complicated cases so maybe it just requires more upfront thought - https://stripe.com/docs/api.

I disagree that REST is a buzzword, though. I think that REST has become so popular because it's a very effective way to construct an API.

afterthought: There are plenty of "RESTful" APIs that miss the mark on important concepts in the pattern. In this case, I would say - yes REST is worthy of the term buzzword.

If you showed Dropbox's RPC API to a REST advocate, they'd probably frown and tell you it's a terrible API because it's not RESTful. You could try to argue that it's not so bad for various reasons, but you still wouldn't be able to win the argument against an ardent REST advocate.

But at the end of the day, Dropbox is probably going to be just fine with their RPC API. So what gives? Why should Dropbox care about REST? How would you sell the CEO on it?

I'd love to read a follow up blog post called "What does REST buy you anyway". Related: https://xkcd.com/1270/


Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is Wrong: http://vimeo.com/30764565

REST APIs must be hypertext-driven: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Hypermedia APIs - Jon Moore: http://vimeo.com/20781278

Designing a RESTful Web API: http://blog.luisrei.com/articles/rest.html

RESTful doesn't mean anything no more than REST means anything, precisely because it's NOT A PROTOCOL and THERE IS NO NORMATIVE SPEC. All this fiasco is due to a vague set of ideas that are in practice no more than JSON-RPC with a http header.

I'm sure you can find 50 developers that will disagree on your definition and that's what hurts all the REST advocates. Your definition is as valid as theirs, until there is a spec that explains precisely what REST is. There is none, there is no normative spec, period.

SOAP has a spec, RPC has a spec, GraphQL has a spec. "REST"(full) has no spec, REST is whatever you think it is.

  > There is none
There isn't a singular spec, no, because REST describes an _set_ of architectures. A family of them. But there is a pretty easy test: do you follow the 6 constraints (though one is optional)? If the answer is yes, then it's RESTful.

> REST is whatever you think it is.

Nonsense. REST is what Dr. Fielding says it is, because he coined the term.

And REST as Dr. Fielding says it is is not as practical to implement as it should be. Hence the need for RESTful which just draws influence from his work.

> And REST as Dr. Fielding says it is is not as practical to implement as it should be.

REST is literally a backwards description of the web and browsers as we know it, so yeah, what are you talking about?

You are downvoted, but also accurate. HTTP 1.0 happened, then Fielding did his work, informing HTTP 1.1. Chronologically speaking, REST is something that describes the web and how it succeeds.

Section 6.3 is even about which parts of HTTP are RESTful or not http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluatio...

> Chronologically speaking, REST is something that describes the web and how it succeeds.

Chronologically speaking, REST is an attempt to fit the relatively-organic growth of the web into a systematized conceptual framework, and a totally untested theory about how it succeeds.

On the first count, it obviously is incorrect. You even pointed out that Fielding points this out! Any part of the web that uses cookies is not RESTful! So REST is not something that "describes the web", it describes an idealized version of the web that in fact has only a tiny fraction of the functionality that the actual web has.

On the second, as far as I'm aware, there is absolutely no evidence supporting Fielding's claims about the relationship between the properties of REST and the success of the web. We may or may not find his points persuasive (I do find his points somewhat persuasive), but please remember that this is someone's thesis, in every sense of that word.

What makes REST impractical?

And if REST isn't practical, we should use a different term to describe what we implement instead.

The meanings of words should be immutable, to avoid confusion. No, that's not how language has historically worked, but we can do better. After all, there are a lot of things we have historically done that we don't want to keep doing.

At a high level, REST is impractical for machine-to-machine interactions where there is no immediate user and hence no need for a user-agent. REST is amazingly practical for things like the human-readable web that we know and love.

If Stripe, e.g., were to build a truly REST machine-to-machine API then they wouldn't need to create any documentation of "endpoints". Developers would only need to point a generic REST client at the API's root URL and all the other endpoints would be discoverable from there.

This is impractical, because a machine-to-machine API will generally know that it wants to charge a credit card or update a billing address and will reap benefits of knowing exactly how to do that without the overhead of going to the root of the API and navigating the resource tree every time.

It can be summed up like this: pure REST is practical in situations where tight-coupling of a client and server's interactions is undesireable. In machine-to-machine interactions, there is almost always some value in tight coupling, or at least a level of coupling that pulls the system away from being "pure" REST. Hence it's rather impractical.

> "The meanings of words should be immutable"

Since when has language historically worked that way? Ever wonder why we have words with 7 officially accepted definitions? Because usage and interpretation changes with time. Perhaps you're confusing language and mathematics?

Why would speaking a human language without nuance, without any possibility of misinterpretation, be a step forward?

It's spelled ReST.

Does that better convey what it means in that string of characters? Maybe for some values of human. But words are for humans, and humans are not immutable, so our words shouldn't be.

> It's spelled ReST.

Really? It's been capitalized REST everywhere I've seen it.

Including here: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...

You weren't thinking of 'reST' (reStructuredText) were you?

No, I was thinking of Representational State Transfer, which is what Fielding's paper talks about. And I was also thinking about how people say RESTful, and how that's a confusing way to say "conforms to how Roy Fielding thinks an API should behave."

What I was responding to was advocacy that human language should behave the way we expect RFCs to work.

It's not quite that simple. He doesn't directly addresses every interpretation.

REST (http://www.ics.uci.edu/%7Efielding/pubs/dissertation/rest_ar...)

HTTP REST (http://cafe.elharo.com/web/why-rest-failed/)

GET/POST vs GET/POST/DELETE/PUT (HTTP REST) (http://www.artima.com/lejava/articles/why_put_and_delete.htm...)

A more recent look at GET/POST over HTTP REST (http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post)

> Nonsense. REST is what Dr. Fielding says it is, because he coined the term.

Yes, and be to accurate,I'm talking of what people call a RESTful architecture in software development.

REST seems to be an API design pattern, rather than a spec.

You can't build a standard REST client since there is no spec, but you can build a libraries that mostly work, since you can identify the pattern quickly.

>REST seems to be an API design pattern, rather than a spec.

IIRC, in an article by Roy Fielding that I read, he said that REST is an architectural style.

But what would that library do? Map discrete input to serialized resource identifiers? Encode or decode resource payloads? Provide transport abstraction? Oh, REST doesn't have an opinion on any of the practical, tangible things a library would implement. Those are always left to the service author without an advertising mechanism for clients.

It doesn't always work, but when it does, its better than having to support an explosion of SDK wrappers that all essentially do the same thing (e.g, provide the services you mention)

> ...set of ideas that are in practice no more than JSON-RPC with a http header.

I'd argue that JSON-RPC (as well as XML-RPC) is more useful than REST, as it has a simple specification that any client/server could follow. If you write a JSON-RPC server, you can expect that any JSON-RPC client would be able to use it.

REST isn't a protocol, it's an argument for an approach to systems architecture that minimizes coupling between components while maximizing client reuse.

I've designed and operated several REST-inspired systems over the years, and let me warn you: it's no walk in the park. Engineers that want to "get it done now" must be convinced not to huck everything up to the server as a POST. Founders have to see the business case for every new system. Other departments may have to relearn tools for interoperating with the systems. It's a whole big deal. You can't deploy a RESTful solution and avoid dealing with people.

For your effort, you'll receive a system with well-factored bounded contexts whose self-descriptive interfaces interoperate with standardized tooling and monitoring systems. Projects can be factored into tasks along clear domains and often incrementally delivered into production. Life-sucking productivity projects like the secret admin website can be pushed off indefinitely. Problems will be simple to isolate and reproduce. You'll have the flexibility to rush out brand new client experiences on tight deadlines.

Notice how none of the problems or benefits really involve a particular technology tool or framework or language?

In my opinion, ignorance of the significant cultural factors required for a successful deployment of a RESTful system is the reason why articles continue to be published about how it's vague or difficult or whatever.

There are lots and lots of open source web applications out there. I like to read code to see how things are being done. Can you point to any web application out there, with source code available to read, that is built in the way that you are describing?

For me personally, the two most important constraints for a legitimate ReST application are:

- HATEOAS - registered mime-types

In particular, the use of registered mime-types. An example:

Say we are building a restful music service similar to Spotify. Say we focus on the list of as users playlists. We can embody the currently logged in users list of playlists as a resource with a specific URL. This URL is opaque to both the client and server.

The representation of this list of playlists could be in the form of a Json hash where key is the playlist name and the value is the URL for the playlist itself.

We also could declare that the following interactions are available to any client that receives this payload from a HTTP GET request: - Create a new playlist - delete a playlist And therefore we can fulfil the HATEOAS requirement.

As I understand it, in order to make this restful we must register this as a custome media type as the additional actions we have defined are part of the available interactions with this media-type.

Don't confuse the content of the representation with a definition of a media-type; we could declare our custom media-type as so:


It is the definition of the media type that dictates that the HATEOAS links in the header with the rel type of create or delete of how clients should interpret them. It is this media-type that dictates this.

It is my understanding that pumping raw Json over http, even with HATEOAS in the headers (or even worse, with links embedded in the Json with the out of band knowledge that a client should interpret our key/value pairs as hypertext based only on the resource URL) is not in anyway restful.

Attempting to define REST is the best way to troll web developers.

RESTful is not a spec, as has been pointed out: it's an idea. It's much more like other large-scale design patterns than it is a protocol. Think "object oriented," or "procedural," not "http" or "tcp." There is only one correct way to implement/use a protocol, but there are many valid expressions of a pattern or idea. It's more or less accepted, I think, that the vast majority of "RESTful" implementation don't obey all the original (15 year old!) guidelines.

It is far more (fundamental) and less (design patterny) than that.

It is akin to to functional programming or declarative database queries. Neither of these are large-scale patterns.

They're both very much about a sane, easy to understand api.

> Stateless does not mean that servers and clients do not have state, it simply means that they do not need to keep track of each other’s state.

For this reason, I've always thought that the term "stateless" is confusing. Maybe "client state independent" (the response that the server sends back is independent of the client's state)? I don't love that term, any better ideas?

I don't think it's confusing because it says exactly what it is supposed to say. 'Stateless' is not a property of the client, or the server, but of the relationship between them, and that relationship is expressed in the protocol they use to communicate.

The relationship between client and server is not stateless in the majority of the cases. Most of the implementations rely on authentication state (cookie, session secret). Very few actually do the stateless part right.

It's probably the biggest problem with pairing HTTP(S)/1.1 and REST. TLS/SSL will require a session that is much more "bound" (entangled?) -- and really would be the sane place to keep track of authentication/id bindings (Who is the client?) -- and use as a basis for authorization (What does this client have access to). But because of the "bolt-on" nature of TLS, we get things like TLS terminating proxies/load-balancers etc, and a lot of passing flags in headers (ProyxN confirms that it's relaying over plain-text HTTP on the (assumed to be) secure internal network, on behalf of clientX that's connected over TLS and has been authenticated...).

The "simple" answer is to have client-certificates, and allow a client access directly to an application server over TLS, or use a secure transport (eg: IPSec), and just use standard HTTP auth on every pass (which AFAIK never was extended to use some form of standardized token, so one's left with sending the actual login/password pair every time).

The sane compromise is to just use encrypted cookies -- but they are also bolt on solutions.

The problem is that essentially one needs encryption to ensure secure sessions, which essentially boil down to authenticating the client to the server, and the server to the client, and forming some kind of session (typically DH for a symmetric session key).

For a long while, encryption was really expensive compared to the db lookup and template render that "every" web application did -- and so we've ended up with a mess of "best practices" which aren't very good at all (and not a very good way of moving from REST-that-trusts-plaintext-ip to REST-and-also-secure).

With HTTP/2 it looks like things are moving towards making the transport-protocol part do the things it should -- track the session, and secure the session. Still doesn't do a good job of authenticating the client in any meaningful way, but it should simplify some of the assumptions that are necessary to build a secure(ish) system.

Agreed, it's very difficult to get to a completely stateless protocol and still support stateful ideas like authentication.

If your authentication token times out, it’s not ReST.

As simple as that.

If you're using an authentication token, it's not really REST. Because of the dire situation wrt. client certificates, the only straight-forward, "pure" REST, would be to supply Basic Auth on every request (that doesn't allow anonymous access).

I'm not really convinced that's not a good idea for a TLS-only service (compared to the complexities that tokens/cookies introduce). One reason why there was a move away from Basic Auth was ofcourse that it is crazy to send plain-text login/password pairs over a plain-text transport (HTTP sans S).

And there's never been any working, cross-platform effort to improve things (AFAIK).

There's some work on Kerberos that's interesting, but again, many of these efforts have been simply co-opted by the fact that everyone used cookies (and had problems, and started encrypting them etc), and then moved from HTTP to HTTPS.

When you have HTTPS, there's not that many reasons to not just have "SECRET PASSWORD" in the URL (granted that'd not be REST either, but BASIC AUTH does the same thing, just in a header).

Indeed, this is the point I wanted to get to.

If you have to do a challenge-response auth every 5 requests, or so, to get a session, then it’s not really rest.

Client certificates might actually make the most sense in this case.

Is that true? The token may have the time encoded in it. When the token is presented to the server it responds with a 401. The client can then use the WWW-Authenticate response to know what to do next.

None of this requires state on the server.

But it requires a state on the client still.

I need to store a state somewhere at least. That’s not really stateless.

Please reconsider this non-sense. Timeouts have nothing to do with being stateless.

A good read: https://www.safaribooksonline.com/library/view/restful-web-s...

Client-agnostic? That seems to imply no id's on the clients at all, though.

I'm reading here that a big problem with many REST APIs is that they don't go all the way with the concept. They fall short of the total, so miss out on the overall benefit.

But if there are any here who are strong advocates, I truly want to know, how do we authenticate in a REST compliment way in practice? Must we, as was pushed early on, only use HTTP basic auth, and resend credentials with each request? Or do we treat the session itself as resource, and somehow refernce it in requests for all other resources? Or are session cookies somehow exempt from the rule that interactions must be stateless?

Actually, they are all valid ways when using the ReST philosophy. The idea is that with every request from the client the latest state is sent along with it (if needed). This way the state of the request can be reconstructed on the server without depending on centralized storage or a single server. The server may update the state and return it for the client to store again (some parts encrypted if needed). No need for the server to keep the state (this way it can remain stateless).

HTTP basic auth does this automatically.

Creating a resource for a session is optional but may be useful if the state to sent back and forth is too big. But this will require centralized storage.

The state may be stored inside a cookie where parts of it can be encrypted. It is also possible to specify that parts can only be updated by the server.

You may also use Local Storage and send the data across using an XMLHttpRequest or even use a HTML form (which may have limited support for the HTTP verbs).

Read my other comment for more information.

But it seems to me that ReST does dictate, specifically, that there must be no need for shared state. The system must work without the client having knowledge of the server and vice versa. But a cookie, as used to hold a session token which references information on the server, is very much shared state. So should be forbidden.

The state is passed back and forth. The server does not keep the state (that is why they call it stateless), the client may keep it. If something does need to be stored on the server a resource should be created. The state that is passed back and forth may then contain a reference to the resource, a resource identifier (in case of the web usually a URI is being used).

The server is stateless because it receives the latest state from the client (location, cookie and other headers) and sends an new updated state (location, set-cookie and other headers) to the client again along with an optional representation. There is no need for the server to keep the state in memory anymore. Because the server does not keep the state it does not matter which copy of the server (in case of load-balancing or fail-over etc.) handles the next request as everything needed can be derived from the state sent along with request from the client.

Keep in mind that it is best practice to be able to reproduce a representation by the use of a resource identifier, like with "pure functions" in functional programming, it should be deterministic. The content of a representation may change but not the semantics of it.

The part that is stateful is the state that is being passed back and forth between the client and the server.

Does that answer your question?

Here's a link to a rant I wrote earlier this year on the same topic


(edited again to make it less rant-y and offensive and more useful)

Can someone suggest an example of "true" REST API, complex enough (not trivial CRUD stuff like blog) to be used as a real-life example?

I look to Stripe's API as the ultimate REST example - https://stripe.com/docs/api.

It's very complicated and follows the pattern very closely.

Stripe's API is good, but it is far from the "ultimate REST example." What is the statistical sample set of APIs that you are comparing from?

From my experience, I would suggest something like Twilio, Github or FoxyCart as the epitome of a REST API.

FamilySearch could be one example https://familysearch.org/developers/docs/guides

GitHub is an example of an API that makes use of HATEOS, and is quite real.

Soooorta. Much of GitHub's core functionality involves either logging in (using cookies. not RESTful.) or using Git (not a MIME type. not HATEOS. not RESTful.).

Still, GitHub is a far more complete RESTful example than most.

Wikipedia might be another not-quite-but-pretty-close example.

The World-Wide Web.

REST came about as a formal description of the architectural patterns that made the WWW a success.

But isn't it a stretch to call the World-Wide Web an "API"? At least in the sense that most people use the term API?

ELI5 for a non-developer?

I always thought it was just a way of sending commands or data to a sever. I created a RESTful (I think) service on a Raspberry Pi that powered on a light every time it got an alert from Salesforce. It did this by POSTing to power.py and parsing in some variables. Is that RESTful?

  >  ELI5 for a non-developer?
There are multiple ways of putting multiple computers together. We call those ways "architectures." This guy named Fielding wrote a dissertation where he describes a number of different properties of different architectures.

In chapter 5, he describes a particular set of properties, for a particular family of architectures, and calls them "REST".

Years later, a whole ton of people misunderstand all this and call all sorts of other things REST.

Confusion abounds.

REST is a series of principals used to structure APIs. Think about if you had a lot more lights on your Raspberry PI. A simple way would be having a call lighting up a specific light. But then the client must track state, in terme of rembering which lights are lit. In a REST sister, you'd request the state of all the lights (typically through a GET http request), which the server would track for you. Then you'd send back the lit or unlit state of all the lights, thereby setting a new state (typically, again, through an http POST request).

I don't see anything non-RESTy about your former example (and would argue it's a BETTER protocol design).

Imagine we want to change the state of light 7 (and only light 7).

A PUT/PATCH of "ON" "OFF" (or 1 or 0 or a float for a dimmer) to http://raspberry1.local/lights/7 to change the status of light 7 is better IMO than doing a GET to http://raspberry1.local/lights and then a PUTS/PATCH to that same URL to update all lights status for the purpose of just updating one light. The latter is obviously fragile in the face of multiple writers (you'll lose updates on overlapping but not colliding writes-an update to light 6 that overlaps in time with light 7 can result in the earlier of those updates being lost when there's no inherent reason for it).

It really depends on the amount of calls you'll have to make. What if you had 10,000 lights? What we tend to do is allow for partial updates with PATCH on just the lights you'd want to change.


PATCH http://bla/url/lights

{ light1: ON, light351: ON, light 4672: ON }

I think that since generally documentation around RESTful API's is generally very good with in-browser demo calls, interpretation of the REST API although differs between implementors, is generally relatively similar enough.

However there are cases where REST design just won't work, or implementing the design abstracts work from the API supplier to the consumer. Where once a "runThisScript(object)" would be easy enough for a developer, now the script itself must be implemented by the developer to call the RESTful endpoints.

In cases like this, we occasionally break REST design for the convenience of developers.

Nothing about this alternative version is any more or less RESTful than the original version.

Generally HTTP REST works on the idea of resources and properties.

so: /lights /lights/light-id /lights/light-id/wattage (return wattage of light)

Doing something like:

/lights/light-id/book-janitor-to-replace which might email and update the janitor's calendar/ToDo list, isn't really following the existing API design.

What do you mean "following the existing API design"?

A good API imo would hide the janitor's calendar/ToDo list unless it was absolutely necessary for the client to access it directly. Then an argument could be made in favor of the booking janitor endpoint on a light - and the API is no less RESTful.

Edit: I don't like it when people over-emphasize resources when talking about REST. I blame this practice on Rails being many people's first introduction to REST. But Rails isn't actually RESTful per Fielding. I prefer to use the term resourceful API to describe the kind of API Rails prescribes. REST is generally in favor of custom endpoints that hide complexity from the client, even at the expense of having a clear cut decision on eg. POST vs PUT/PATCH for a given endpoint.

I only bring this up because this is the topic of the article; that may be "REST as people talk about it" but none of that has anything to do with "what RESTful actually means".

Have been using the ReST philosophy (or pattern?) for almost 15 years without any issues. ReST itself does not define the use of a specific technology and is not a standard by itself, it is pretty abstract. Using the URI and HTTP standards are just a way to apply it. Other technologies can be used as well, like SMTP / MIME or something developed yourself as soon as the ReST constraints can be applied. Adding the ReST constraints is what brings the advantages. It is really flexible and allows for easy composition of "layers" through "connectors". A caching proxy is an example of a "connector". If ReST could be compared to something in programming it is very similar to "monads" as used in functional programming.

Recursion can be done by the use of nested "resource identifiers" (SSI or ESI for example) inside the returned "representation". A "connector" may then decide to do another request to replace the "identifier". If the "connector" uses caching it may not even need to do another sub-request. I use this to do something like what Facebook's Relay does. As the full state is always being sent along with every request it is very easy to scale because the servers, wherever they are, always have enough context to be able to work with it. A server may even ignore what it does not understand for the next layer to handle it called "partial understanding" which is supported by XML for example. Unfortunately when using JSON most of these advantages are lost. That is why I prefer a less verbose "XML Infoset" similar to JSON while still keeping all the advantages.

This is sorta helpful. But what would be illuminating and almost never gets done is the very simple description of what a real world API would look like that corresponds to the description. And there are zillions to choose from to take a crack at.

If you have an interest in distributed computing "The End of Protocols" is a great read:


The whole RPC vs. REST thing is not a useful distinction.

my only question regarding RESTful api's is... is it really that hard to implement?

I know there's a few set of rules/principles to follow but in the end, I just see "lets make a readable and easy-to-understand API that has a nice set of plural "subjects" with the basic HTTP request verbs all nicely applied.

I ask this because I noticed while applying for jobs, that some people hiring simply want someone who can write a REST API but I just didn't see it as a big deal when you're hiring a web developer as long as he has the experience and good mentality for creating organized code.

Also there is this 5 year old book "REST in Practice" which defines several levels of RESTfulness

I ask candidates to explain this when I interview them. I read that first paragraph and was upset/unsurprised.

What do you expect them to respond? It's not very well defined.

I would probably say...

""" REST, like many great religious philosophies, combines with one's life experience to mean something different for every pair of eyes that looks at it. For me, it's something which has URLs for resources of the form

and default HTTP methods of GET / POST / DELETE to read / modify / remove instances. Finally, while I realize this is a bit too implementation detail-y than most definitions, my mind is not really at rest unless an HTTP API respond with JSON and reference other instances in some standardized way.

You will notice the repetition of sets of 3, and that's because 3 is my favorite number. I also really like the Stripe API's way of specifying arrows to related content to "unfold" references in the JSON response. That really puts my mind at rest when I see it, so that's RESTful, as well.

To get a little more real, though, REST is totally the old hotness and verging on not even being that hot. All the cool kids now know to use GraphQL, and if you aren't at least planning to transition to it, I'm not really interested in working here unless you pay me a lot of money. """

How'd I do?

Well, strictly speaking if your having to explain the structure of your URLs then it's not really fully REST (because of HATEOS) and I don't think there is any requirement for a RESTful interface to return JSON.

But having said that I've got the point where I don't really care - if I can interact with an API from curl without too much difficulty I don't care if the API is fully REST or not.

I'm deeply offended that you called my URL structure un-REST-ful and challenge you to come up with an API spec that's more REST-ful than mine.

The parent was being sarcastic.

It's pretty well defined that's how we get blog posts like this one.

It's literally a backwards explanation of the web and browsers.

It's really not, hence why we get blog posts like this one.

workitout's response is less tongue-in-cheek, if you prefer that: https://news.ycombinator.com/item?id=10767440

If they say it is a set of guidelines and not a guaranteed, deterministic, contractual architecture like SOAP and there are many ways to interpret the meaning of "restful"; do they pass your interview?

So what do you call a system that uses more than two HTTP methods (e.g. uses PUT and DELETE as well as GET and POST), and has marginally-more-human-readable URLs, but doesn't send self-descriptive representations, doesn't use hypermedia, doesn't Transfer REpresentational State, and probably also isn't stateless?

I mean, statistically speaking, if you have such a system, my bet is that you call that system RESTful. Furthermore, if you have such a system, you vastly outnumber the people building systems that obey Fielding's constraints. So in practice, you win the argument about what "RESTful" means.

Can we please stop legitimizing Rails's whimsical aesthetic choices by pretending that they have something to do with an academically-justified architecture, and just accept that they're just another way of ripping your denim and then safety-pinning it closed, by which you demonstrate that you're not a square and you don't write Java.

> "So what do you call a system that uses more than two HTTP methods (e.g. uses PUT and DELETE as well as GET and POST), and has marginally-more-human-readable URLs, but doesn't send self-descriptive representations, doesn't use hypermedia, doesn't Transfer REpresentational State, and probably also isn't stateless?"

What's wrong with calling it an HTTP API?

> Can we please stop legitimizing Rails's whimsical aesthetic choices by pretending that they have something to do with an academically-justified architecture, and just accept that they're just another way of ripping your denim and then safety-pinning it closed, by which you demonstrate that you're not a square and you don't write Java.

Please don't do this here. Snark like this is good for starting technical flamewars but it invariably lowers the quality of the discussion.

Even though you're right this line almost made it all worth it in terms of comedic value: "...accept that they're just another way of ripping your denim and then safety-pinning it closed, by which you demonstrate that you're not a square and you don't write Java."

Sigh, maybe Client-Server or Remote Data Access?:

"3.4.7 Remote Data Access (RDA)

The remote data access style [131] is a variant of client-server that spreads the application state across both client and server. A client sends a database query in a standard format, such as SQL, to a remote server. The server allocates a workspace and performs the query, which may result in a very large data set. The client can then make further operations upon the result set (such as table joins) or retrieve the result one piece at a time. The client must know about the data structure of the service to build structure-dependent queries."


REST is a very specific architecture, with very specific constraints. Not everything is REST, not everything should be REST. And there's certainly no reason to call things REST, if what one means is simply a client-server application over HTTP. But if what one is building is "just" client-server, perhaps HTTP isn't the best transport.

REST is what Dr. Fielding says it is, since he coined the term. Anything else can just be called an HTTP API. What does Rails have to do with it?

Sometimes it feels like nobody has read Fielding and that people just make up what REST is to be what Rails prescribes.

From seeing your arbitrary attack against Ruby on Rails, an 11(!) year old framework, I'm going to guess that you'd be like those guys in the 90's who were saying "almost-ACID" databases were good enough.

Arbitrary attacks galore!

Applications are open for YC Summer 2019

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact