12 ms·

What RESTful actually means

233 points by luu 11y ago

jholman 11y ago
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.
- herge 11y ago
  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.
  - oldmanjay 11y ago
    Arbitrary attacks galore!
- hhariri 11y ago
  > "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?
- mwcampbell 11y ago
  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?
  - gkop 11y ago
    Sometimes it feels like nobody has read Fielding and that people just make up what REST is to be what Rails prescribes.
- dang 11y ago
  > 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.
  - brazzledazzle 11y ago
    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."
- e12e 11y ago
  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." http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_styles.htm#sec_3_4 http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_... 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.
hashkb 11y ago
I ask candidates to explain this when I interview them. I read that first paragraph and was upset/unsurprised.
- workitout 11y ago
  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?
- andreyf 11y ago
  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 /<class_name>(/<instance_id>(/<custom_method>)?)? 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?
  - arethuza 11y ago
    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.
deleted 11y ago
[deleted]
adamzerner 11y ago
> 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?
- andreyf 11y ago
  Client-agnostic? That seems to imply no id's on the clients at all, though.
- markbnj 11y ago
  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.
  - tie_ 11y ago
    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.
    - kuschku 11y ago
      If your authentication token times out, it’s not ReST. As simple as that.
      - emmelaich 11y ago
        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.
7ewis 11y ago
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?
- steveklabnik 11y ago
  > 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.
- herge 11y ago
  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).
  - sokoloff 11y ago
    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 http://raspberry1.local/lights/7 to change the status of light 7 is better IMO than doing a GET to http://raspberry1.local/lights 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).
aikah 11y ago
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.
- steveklabnik 11y ago
  > 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.
- tarr11 11y ago
  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.
  - jonhohle 11y ago
    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.
    - tarr11 11y ago
      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)
teddyh 11y ago
Related: Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is Wrong: http://vimeo.com/30764565 http://vimeo.com/30764565 REST APIs must be hypertext-driven: http://roy.gbiv.com/untangled/2008/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 http://vimeo.com/20781278 Designing a RESTful Web API: http://blog.luisrei.com/articles/rest.html http://blog.luisrei.com/articles/rest.html
markbnj 11y ago
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.
- emmelaich 11y ago
  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.
xirdstl 11y ago
Attempting to define REST is the best way to troll web developers.
cuillevel3 11y ago
Also there is this 5 year old book "REST in Practice" which defines several levels of RESTfulness
virde 11y ago
Here's a link to a rant I wrote earlier this year on the same topic https://medium.com/@vrashabhirde/will-the-real-restful-api-please-stand-up-ea612a92b9a9#.88ft4t66s https://medium.com/@vrashabhirde/will-the-real-restful-api-p... (edited again to make it less rant-y and offensive and more useful)
jalfresi 11y ago
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: Application/vnd.spotify.com.list.playlists+Json 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.
pixie_ 11y ago
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.. https://www.dropbox.com/developers/documentation/http/documentation https://www.dropbox.com/developers/documentation/http/docume...
- krainboltgreene 11y ago
  > 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.
  - tie_ 11y ago
    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.
    - 11y ago
vbezhenar 11y ago
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?
- nbrempel 11y ago
  I look to Stripe's API as the ultimate REST example - https://stripe.com/docs/api https://stripe.com/docs/api. It's very complicated and follows the pattern very closely.
  - mahmoudimus 11y ago
    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.
- steveklabnik 11y ago
  GitHub is an example of an API that makes use of HATEOS, and is quite real.
  - jholman 11y ago
    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.
- JimDabell 11y ago
  The World-Wide Web. REST came about as a formal description of the architectural patterns that made the WWW a success.
  - sopooneo 11y ago
    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?
pbreit 11y ago
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.
politician 11y ago
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.
- jmcqk6 11y ago
  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?
deeteecee 11y ago
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.
wstrange 11y ago
If you have an interest in distributed computing "The End of Protocols" is a great read: http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/infra/waldo-end-of-proto.pdf http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/i... The whole RPC vs. REST thing is not a useful distinction.
machuidel 11y ago
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.
sopooneo 11y ago
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?
- machuidel 11y ago
  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.
  - sopooneo 11y ago
    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.
    - machuidel 11y ago
deleted 11y ago
[deleted]

233 points by luu 11y ago

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.

herge 11y ago
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.
- oldmanjay 11y ago
  Arbitrary attacks galore!
hhariri 11y ago
> "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?
mwcampbell 11y ago
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?
- gkop 11y ago
  Sometimes it feels like nobody has read Fielding and that people just make up what REST is to be what Rails prescribes.
dang 11y ago
> 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.
- brazzledazzle 11y ago
  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."
e12e 11y ago
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." http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_styles.htm#sec_3_4 http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_... 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.

hashkb 11y ago

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

workitout 11y ago
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?
andreyf 11y ago
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 /<class_name>(/<instance_id>(/<custom_method>)?)? 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?
- arethuza 11y ago
  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.

deleted 11y ago

[deleted]

adamzerner 11y ago

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

andreyf 11y ago
Client-agnostic? That seems to imply no id's on the clients at all, though.
markbnj 11y ago
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.
- tie_ 11y ago
  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.
  - kuschku 11y ago
    If your authentication token times out, it’s not ReST. As simple as that.
    - emmelaich 11y ago
      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.

7ewis 11y ago

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?

steveklabnik 11y ago
> 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.
herge 11y ago
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).
- sokoloff 11y ago
  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 http://raspberry1.local/lights/7 to change the status of light 7 is better IMO than doing a GET to http://raspberry1.local/lights 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).

aikah 11y ago

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.

steveklabnik 11y ago
> 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.
tarr11 11y ago
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.
- jonhohle 11y ago
  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.
  - tarr11 11y ago
    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)

teddyh 11y ago

Related: Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is Wrong: http://vimeo.com/30764565 http://vimeo.com/30764565 REST APIs must be hypertext-driven: http://roy.gbiv.com/untangled/2008/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 http://vimeo.com/20781278 Designing a RESTful Web API: http://blog.luisrei.com/articles/rest.html http://blog.luisrei.com/articles/rest.html

markbnj 11y ago

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.

emmelaich 11y ago
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.

xirdstl 11y ago

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

cuillevel3 11y ago

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

virde 11y ago

Here's a link to a rant I wrote earlier this year on the same topic https://medium.com/@vrashabhirde/will-the-real-restful-api-please-stand-up-ea612a92b9a9#.88ft4t66s https://medium.com/@vrashabhirde/will-the-real-restful-api-p... (edited again to make it less rant-y and offensive and more useful)

jalfresi 11y ago

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: Application/vnd.spotify.com.list.playlists+Json 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.

pixie_ 11y ago

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.. https://www.dropbox.com/developers/documentation/http/documentation https://www.dropbox.com/developers/documentation/http/docume...

krainboltgreene 11y ago
> 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.
- tie_ 11y ago
  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.
  - 11y ago

vbezhenar 11y ago

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?

nbrempel 11y ago
I look to Stripe's API as the ultimate REST example - https://stripe.com/docs/api https://stripe.com/docs/api. It's very complicated and follows the pattern very closely.
- mahmoudimus 11y ago
  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.
steveklabnik 11y ago
GitHub is an example of an API that makes use of HATEOS, and is quite real.
- jholman 11y ago
  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.
JimDabell 11y ago
The World-Wide Web. REST came about as a formal description of the architectural patterns that made the WWW a success.
- sopooneo 11y ago
  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?

pbreit 11y ago

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.

politician 11y ago

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.

jmcqk6 11y ago
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?

deeteecee 11y ago

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.

wstrange 11y ago

If you have an interest in distributed computing "The End of Protocols" is a great read: http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/infra/waldo-end-of-proto.pdf http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/i... The whole RPC vs. REST thing is not a useful distinction.

machuidel 11y ago

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.

sopooneo 11y ago

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?

machuidel 11y ago
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.
- sopooneo 11y ago
  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.
  - machuidel 11y ago

deleted 11y ago

[deleted]