Ask HN: What is REST exactly?
I've read several articles about REST, even a bit of the original paper. But I still have quite a vague idea about what it is. I'm beginning to think that nobody knows, that it's simply a very poorly defined concept. Like Web 2.0, everyone talked about it but nobody could give a clear definition. Thoughts?
26 comments
REST is an architectural style. It is a formalisation of Fielding's observation how the Web works.
A RESTful interface follows those principles and must employ hyperlinks (links in HTML, XLink in XML, _links property in HAL+JSON) and/or hypermedia controls (forms, XForms) and standard HTTP methods to assert state on resources. Resources are adressed by URIs.
An interface description concentrates on describing the semantics of media types of the resources (unless you were clever and picked an appropriate one that already exists) and link relations ("a", "link", "area" element with "rel" attribute in HTML; link objects in HAL+JSON; RFC 5988 Link headers for any media type). Link relations are standardised by IANA, but you can make your own one and assign some semantics to it by coining a URI. When an interface describes particular URIs (what you typically get when you google for REST interface examples), it's doing it wrong. An interface implementation allows a user agent to discover resources through hyperlinks and what you can do with them through an OPTIONS request. You can recognise a REST n00b by their lack of talking about link relations, which is so far everyone else's answers. I must consider colund's and dclara's answers as wrong/unhelpful because their explanation is so limited and unprecise.
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... http://isitrestful.com/
A RESTful interface follows those principles and must employ hyperlinks (links in HTML, XLink in XML, _links property in HAL+JSON) and/or hypermedia controls (forms, XForms) and standard HTTP methods to assert state on resources. Resources are adressed by URIs.
An interface description concentrates on describing the semantics of media types of the resources (unless you were clever and picked an appropriate one that already exists) and link relations ("a", "link", "area" element with "rel" attribute in HTML; link objects in HAL+JSON; RFC 5988 Link headers for any media type). Link relations are standardised by IANA, but you can make your own one and assign some semantics to it by coining a URI. When an interface describes particular URIs (what you typically get when you google for REST interface examples), it's doing it wrong. An interface implementation allows a user agent to discover resources through hyperlinks and what you can do with them through an OPTIONS request. You can recognise a REST n00b by their lack of talking about link relations, which is so far everyone else's answers. I must consider colund's and dclara's answers as wrong/unhelpful because their explanation is so limited and unprecise.
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... http://isitrestful.com/
This is the most accurate answer I've seen here (in terms of how Fielding described it).
The way he defines it in the dissertation is as a series of architectural constraints which evoke certain properties [1]. Those constraints are titled with "Client-Server", "Stateless", "Cache", "Uniform Interface", "Layered System", and "Code-On-Demand".
Your description of link relations is also correct. Links are the basis of all REST interoperation, whether for humans or APIs. I've been evangelizing the use of the Link header [2], which benefits from
2. http://tools.ietf.org/html/rfc5988
The way he defines it in the dissertation is as a series of architectural constraints which evoke certain properties [1]. Those constraints are titled with "Client-Server", "Stateless", "Cache", "Uniform Interface", "Layered System", and "Code-On-Demand".
Your description of link relations is also correct. Links are the basis of all REST interoperation, whether for humans or APIs. I've been evangelizing the use of the Link header [2], which benefits from
1) a standard format regardless of content-type
2) the ability to be fetched with HEAD
3) the "relation type", which can be used to make strong assumptions about the endpoint
2. http://tools.ietf.org/html/rfc5988
The only misleading part of this is "must employ...standard HTTP methods to assert state on resources". REST does not require using HTTP -- in fact, your own first link states, as its first rule, "A REST API should not be dependent on any single communication protocol".
Its true that whatever protocol(s) it uses should be used in standard (not resource-specific) way, but there is no requirement that HTTP be the only protocol, or one of the protocols, used.
Its true that whatever protocol(s) it uses should be used in standard (not resource-specific) way, but there is no requirement that HTTP be the only protocol, or one of the protocols, used.
> REST is an architectural style
This is one of the things I don't understand. Architectural style for what, interfaces?
> must employ hyperlinks
A weird restriction imho. Links make sense for web pages read by humans. But APIs? Yes, links are nice to quickly get to know the API, to test it via a browser but they're not that important.
This is one of the things I don't understand. Architectural style for what, interfaces?
> must employ hyperlinks
A weird restriction imho. Links make sense for web pages read by humans. But APIs? Yes, links are nice to quickly get to know the API, to test it via a browser but they're not that important.
> > must employ hyperlinks
> A weird restriction imho. Links make sense for web pages read by humans. But APIs? Yes, links are nice to quickly get to know the API, to test it via a browser but they're not that important.
The use of hypermedia is central to REST -- if you think "hyperlinks aren't important to APIs", that's equivalent to reject the REST architecture.
In REST, you don't need a map of service endpoints or conventions about locations to consume an API. You need to know one resource location, and understand the representation of the resource that can be retrieved there, and from that the rest of the API should be discoverable -- moreover, the locations of the other resources can change and you can still use the API.
(And this is scalable, so that what is from one perspective the "root" resource location for one API can also be a link provided by another resource, such that if you know how to retrieve the latter resource, the location of the other API root can change and you can still consume it.)
> A weird restriction imho. Links make sense for web pages read by humans. But APIs? Yes, links are nice to quickly get to know the API, to test it via a browser but they're not that important.
The use of hypermedia is central to REST -- if you think "hyperlinks aren't important to APIs", that's equivalent to reject the REST architecture.
In REST, you don't need a map of service endpoints or conventions about locations to consume an API. You need to know one resource location, and understand the representation of the resource that can be retrieved there, and from that the rest of the API should be discoverable -- moreover, the locations of the other resources can change and you can still use the API.
(And this is scalable, so that what is from one perspective the "root" resource location for one API can also be a link provided by another resource, such that if you know how to retrieve the latter resource, the location of the other API root can change and you can still consume it.)
Architectural style for building scalable applications. Fielding wasn't talking about APIs specifically.
There's nothing "weird" about links in APIs. For an easy metaphor, think of "links" in APIs as you think of foreign keys in your database tables. Link doesn't just mean something you can click :)
There's nothing "weird" about links in APIs. For an easy metaphor, think of "links" in APIs as you think of foreign keys in your database tables. Link doesn't just mean something you can click :)
http://isitrestful.com/
I'd be interested to know what this site precisely checks for. Anyone got any ideas?
I'd be interested to know what this site precisely checks for. Anyone got any ideas?
In my understanding REST is just a name for when HTTP (and in particular its verbs GET, PUT, POST, DELETE, HEAD) are used to operate on data (resources) by using URL paths, headers and data. The objective is something similar to the good old "remote procedure call" concept where computers can invoke actions on remote computers. There used to be complicated technologies like CORBA and plain RMI to aid computers in being able to communicate with each others.
Modern often means simple. It should be easy to operate or resources via a web API and REST is often the answer. Use the HTTP technology which is already there and embrace it and create technologies around it. KISS principle is king, as opposed to inventing a proprietary complex and useless own method of data communication.
Modern often means simple. It should be easy to operate or resources via a web API and REST is often the answer. Use the HTTP technology which is already there and embrace it and create technologies around it. KISS principle is king, as opposed to inventing a proprietary complex and useless own method of data communication.
REST is a light-weight implementation of Web Service, which evolved from other distributed architecture solutions, such as CORBA, RMI, COM/DCOM, SOAP, SOA with XML. Here is a brief report on the history of Web Service: http://bit.ly/1jkySqU
But instead of XML, it employs data format of JSON to reduce the data size and every time it only returns a portion of the data, instead of return a complete set of data according to XML schema. This saves a lot of time for fast communication, especially if the application data set is small and simple, such as chatting.
But one interesting question is: Axis has one mode using RPC call, which is pretty fast and flexible based on SOAP using object serialization. But it's no longer popular now. Do you know why? There is a little trick of the object serializing when passing the parameters, though. But it can do RPC call so easily than the key/value pairs of JSON.
But instead of XML, it employs data format of JSON to reduce the data size and every time it only returns a portion of the data, instead of return a complete set of data according to XML schema. This saves a lot of time for fast communication, especially if the application data set is small and simple, such as chatting.
But one interesting question is: Axis has one mode using RPC call, which is pretty fast and flexible based on SOAP using object serialization. But it's no longer popular now. Do you know why? There is a little trick of the object serializing when passing the parameters, though. But it can do RPC call so easily than the key/value pairs of JSON.
REST doesn't have to be JSON, it's agnostic with regard to the serialization format. JSON is just a popular format but I've seen XML and YAML REST apis.
REST has two different meanings, which I outline below. Both say each URL identifies a resource, which is represented with a document of some kind.
* The practical, common usage is a remote API built on HTTP, which uses HTTP verbs in a logical manner, exchanging JSON.
* The original meaning is what I believe is now better referred to as "Hypermedia as the engine of state" (HATEOS). In this world a URLs are not meaningful, and clients never construct or parse URLs. Instead a document format (hypermedia) specifies URLs and indicates what they do. The document format drives and defines the API.
This difference causes some arguments: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
* The practical, common usage is a remote API built on HTTP, which uses HTTP verbs in a logical manner, exchanging JSON.
* The original meaning is what I believe is now better referred to as "Hypermedia as the engine of state" (HATEOS). In this world a URLs are not meaningful, and clients never construct or parse URLs. Instead a document format (hypermedia) specifies URLs and indicates what they do. The document format drives and defines the API.
This difference causes some arguments: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
When I was defining our API at Synference, I looked this up.
As far as I'm concerned, pragmatically, its using the HTTP verbs to operate on resources, named according to a certain URL convention (e.g. users/<userid>), when the semantics of the verbs are followed.
E.g. GET shouldn't change resource state; POST should be used to create a new resource (which the server will typically name); PUT should be used to update an existing named resource, etc.
What format of data sent using these verbs can vary - JSON is one popular format, and what I'd choose.
However, in practice, when people say their API is RESTful, it often just means 'you can access our API over HTTP'. Often you see everything implemented as GET requests - for better or worse.
And there are some pragmatic reasons for that - e.g. maybe devs decide they want to use JSONP to get around same origin restrictions; there's web developers out there who can only make GET requests, etc.
As far as I'm concerned, pragmatically, its using the HTTP verbs to operate on resources, named according to a certain URL convention (e.g. users/<userid>), when the semantics of the verbs are followed.
E.g. GET shouldn't change resource state; POST should be used to create a new resource (which the server will typically name); PUT should be used to update an existing named resource, etc.
What format of data sent using these verbs can vary - JSON is one popular format, and what I'd choose.
However, in practice, when people say their API is RESTful, it often just means 'you can access our API over HTTP'. Often you see everything implemented as GET requests - for better or worse.
And there are some pragmatic reasons for that - e.g. maybe devs decide they want to use JSONP to get around same origin restrictions; there's web developers out there who can only make GET requests, etc.
Just to ride on this, the "named according to a certain URL convention" isn't a set thing. You can have any convention as long as it's the same everywhere.
What is a resource exactly? Is GET /sumof/2/5 -> 7 a resource?
Yes in principle, but that's a dumb way to do it. A client programmer might infer something generalised from this example and be tempted to hard-code /sumof in his user agent, which makes the server lose controls of its URI namespace, which in turn the prevents the affair from being RESTful.
Instead, you express your summing service with a hypermedia control. In HTML you have forms, which is a perfectly fine and very interoperable way; look at all the deployed software understanding HTML forms! Another control fitting the example here is to send the client an RFC 6570 URI template (I'm uncertain of the correct syntax with the * in detail here, sorry, take this as illustration only):
Instead, you express your summing service with a hypermedia control. In HTML you have forms, which is a perfectly fine and very interoperable way; look at all the deployed software understanding HTML forms! Another control fitting the example here is to send the client an RFC 6570 URI template (I'm uncertain of the correct syntax with the * in detail here, sorry, take this as illustration only):
Link: </sumof/{summand*}>;
rel="http://RivieraKid.example.net/summing_service";
title="RivieraKid's summing service";
hreflang="en";
type="application/hal+json; profile=http://RivieraKid.example.net/"
slashdotaccount, hit me up on twitter @pfrazee. I think we're looking at the same ideas
You can think of "resource" as an object in your application exposed on the web. REST actually talks about "resource representations" not: resources per se. This has to do with the Facade pattern and not tying your public interface with your internal implementation.
That said, for getting started you can think as "resource" being a web-addressable representation of an object in your application.
That said, for getting started you can think as "resource" being a web-addressable representation of an object in your application.
I think the word "resource" is a source of confusion. It doesn't make any sense to mortals.
Yes! You hit the nail on the head.
It's really worth reading the thesis that started it all (http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) and I also find this HATEOAS article (http://timelessrepo.com/haters-gonna-hateoas) worthwhile reading, but to answer your question succinctly, here's my short definition:
"REST is inter-computer communication structured such that the server doesn't maintain any client state so that neither the duration between requests nor the number of clients impacts the resource usage of the server."
It's not quite true, but the architecture has benefits:
1) No need to replicate client sessions in a clustered environment.
2) There's no impact if a client wait hours between requests.
3) Every resource a client uses has a unique location on the network.
"REST is inter-computer communication structured such that the server doesn't maintain any client state so that neither the duration between requests nor the number of clients impacts the resource usage of the server."
It's not quite true, but the architecture has benefits:
1) No need to replicate client sessions in a clustered environment.
2) There's no impact if a client wait hours between requests.
3) Every resource a client uses has a unique location on the network.
"Haters" author here, glad you've found it useful.
I will mention that "nobody" is doing this is wrong nowadays. GitHub is one example, and my employer, Balanced is another. Go on, try it:
If you GET that card with the same credentials, you'll find a link in the response that points to how to debit.
I will mention that "nobody" is doing this is wrong nowadays. GitHub is one example, and my employer, Balanced is another. Go on, try it:
curl https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo/debits \
-H "Accept-Type: application/vnd.api+json;revision=1.1" \
-u ak-test-1sKqYrBZG6WYpHphDAsM7ZXFEmJlAn1GE: \
-d "appears_on_statement_as=Hacker News" \
-d "amount=5000" \
-d "description=A sample charge to show hypermedia controls"
If you GET that card with the same credentials, you'll find a link in the response that points to how to debit.
Ok, I read your article about HATEOAS and there is one thing that bothers me about the discoverability aspect. The example of the discoverable "newcomment" action that can be done on the resource has no clear semantics; it's just an anonymous link. You claim that you could arbitrarily change the link and a good client would follow along, but how did a client even know that /entry/newcomment was the way to make a new comment in the first place, let alone after you rename it to /somethingelse/whatever?
I assume the examples are just suffering from being oversimplified, because otherwise the whole scheme seems like a huge sham, but I really don't understand how a client is supposed to magically discover the correct endpoint.
I assume the examples are just suffering from being oversimplified, because otherwise the whole scheme seems like a huge sham, but I really don't understand how a client is supposed to magically discover the correct endpoint.
HATEOAS isn't the semantic web. You still need a human to translate what exactly "/entry/newcomment" _means_, in the software sense.
But once you have a client that understands one specific vocabulary, if you will, you can use the same client for multiple services which speak that vocabulary.
As an example, think about RSS: RSS is a standard, built on top of XML, which shares certain structures and link relations. A human builds an RSS reader, which understands the RSS format, and then you can use that reader on any RSS-enabled site.
Another example is https://gist.github.com/steveklabnik/2187514 , which understands the 'ALPS microblogging' spec. You can use this microblogging client across any compatible server: http://rstat.us and http://alps-microblog.herokuapp.com/ are two instances.
But once you have a client that understands one specific vocabulary, if you will, you can use the same client for multiple services which speak that vocabulary.
As an example, think about RSS: RSS is a standard, built on top of XML, which shares certain structures and link relations. A human builds an RSS reader, which understands the RSS format, and then you can use that reader on any RSS-enabled site.
Another example is https://gist.github.com/steveklabnik/2187514 , which understands the 'ALPS microblogging' spec. You can use this microblogging client across any compatible server: http://rstat.us and http://alps-microblog.herokuapp.com/ are two instances.
I'm still not clear on how this is possible: "By the same token, we can change the URI in our <link> tag, and a proper client will just automatically follow along. Brilliant!" If your client has a notion of what exactly "/entry/newcomment" _means_, then how is it going to automatically follow along when the link URI changes?
Before:
{ "/entry/newcomment": "/foo" }
After:
{ "/entry/newcomment": "/bar" }
Because the code says "send a POST request to whatever URL is at the end of the correct rel", it will make a POST to /foo in the first instance, but /bar in the second.
And it also recognizes if such a thing is even present. So, for example: https://gist.github.com/steveklabnik/2187514#file-microblog_...
This implies that _if_ the form with this class is on the page, then we show the "post a new microblog" button. If it's not, then we don't. The client automatically adapts to the server's response.
And where to POST _to_ is here: https://gist.github.com/steveklabnik/2187514#file-microblog_...
Maybe this helps? http://words.steveklabnik.com/i-invented-hypermedia-apis-by-...
Also, I have a mailing list where we discuss this kind of thing: [email protected] . That might be easier than checking HN history, and others can chime in too.
{ "/entry/newcomment": "/foo" }
After:
{ "/entry/newcomment": "/bar" }
Because the code says "send a POST request to whatever URL is at the end of the correct rel", it will make a POST to /foo in the first instance, but /bar in the second.
And it also recognizes if such a thing is even present. So, for example: https://gist.github.com/steveklabnik/2187514#file-microblog_...
This implies that _if_ the form with this class is on the page, then we show the "post a new microblog" button. If it's not, then we don't. The client automatically adapts to the server's response.
And where to POST _to_ is here: https://gist.github.com/steveklabnik/2187514#file-microblog_...
Maybe this helps? http://words.steveklabnik.com/i-invented-hypermedia-apis-by-...
Also, I have a mailing list where we discuss this kind of thing: [email protected] . That might be easier than checking HN history, and others can chime in too.
Gotcha, thanks. I knew I must be missing something, and that's it.
No problem. At this point, server-side knowledge is pretty known, but client-side understanding is harder to come by. Those of us on the bleeding edge are working on making it more accessible, but it just requires time and resources our merry little band doesn't always have, you know?
Wow ... Nice to meet you Steve! I'm going to bow out of the discussion since there's an expert here.
Pssssh. Don't do that!
I think you're initial thought is correct - it's not very well-defined. Indeed, the joke is that REST's primary utility is that it enables you to criticize anything with "but it's not RESTful". Indeed, Roy Fielding himself used to be famous for this.
What REST has come to mean, to me (and perhaps to others), is a URL style whereby data, including application state, is addressed in a hierarchical way. However, I don't think that's what Roy really meant.
The wikipedia article is not bad: https://en.wikipedia.org/wiki/REST
What REST has come to mean, to me (and perhaps to others), is a URL style whereby data, including application state, is addressed in a hierarchical way. However, I don't think that's what Roy really meant.
The wikipedia article is not bad: https://en.wikipedia.org/wiki/REST
I can't give you the academic answer, but I can tell you what it means in practice.
Rest is a standardized way of structuring url's and http verbs.
For instance:
1) To get all "posts" from a blog, you send a GET request to www.whatever.com/posts
2) To read a single post, you send a GET request to www.whatever.com/posts/<id>
3) To create a single post, you send a POST request to www.whatever.com/posts
4) Finally, to get all comments from a post, you send a GET request to www.whatever.com/posts/<id>/comments
Rest is a standardized way of structuring url's and http verbs.
For instance:
1) To get all "posts" from a blog, you send a GET request to www.whatever.com/posts
2) To read a single post, you send a GET request to www.whatever.com/posts/<id>
3) To create a single post, you send a POST request to www.whatever.com/posts
4) Finally, to get all comments from a post, you send a GET request to www.whatever.com/posts/<id>/comments
REST is best described by the original paper. There are many other ways to describe it.
I like to think of the basic idea of REST as CRUD over HTTP. Think about how you interact with a database and move that abstraction out to a service level. Instead of doing things like "sign in", "leave group", "down vote entry" you instead "create session", "delete membership", "update entry". That's the key concept.
I like to think of the basic idea of REST as CRUD over HTTP. Think about how you interact with a database and move that abstraction out to a service level. Instead of doing things like "sign in", "leave group", "down vote entry" you instead "create session", "delete membership", "update entry". That's the key concept.
Lot's of people describing HTTP here, but that's not REST. REST is transport agnostic and has a lot of other things going on it like resource discovery.
I still hold to my belief that nobody actually knows how to do "real" REST, but most everybody implements some subset of it - which is fine.
I still hold to my belief that nobody actually knows how to do "real" REST, but most everybody implements some subset of it - which is fine.
Hence the Ask HN.
People don't do it right because pretty much every description is unintelligible (for example, most of the attempts on this thread).
People don't do it right because pretty much every description is unintelligible (for example, most of the attempts on this thread).
Intro to REST (aka. What Is REST Anyway?)
http://www.youtube.com/watch?v=llpr5924N7E
I like Fowler's explanation.
http://martinfowler.com/articles/richardsonMaturityModel.htm...
http://martinfowler.com/articles/richardsonMaturityModel.htm...
It's about using the existing infrastructure of the web (HTTP, hyperlinks), leveraging it as much as you can (caching, content negotiation, etc.) and putting as little shit on top of it as you can (please no SOAP!)
If you actually mean HATEOAS then it gets a bit more complex, but in practice most people just interpret that as 'it should be discoverable just like a website is.'
If you actually mean HATEOAS then it gets a bit more complex, but in practice most people just interpret that as 'it should be discoverable just like a website is.'
Mostly, it means using HTTP verbs on URLs to represent create/update/read/delete. (IE, POST/PUT/GET/DELETE)
There are other intricacies like HATEOAS (which sounds like a horrible breakfast cereal), but it basically mostly comes down to updating resources using http verbs.
Whee.
(Personally I don't get the reverence it gets since it's basically just about verbs and locations, but whatever, it works well enough).
There are other intricacies like HATEOAS (which sounds like a horrible breakfast cereal), but it basically mostly comes down to updating resources using http verbs.
Whee.
(Personally I don't get the reverence it gets since it's basically just about verbs and locations, but whatever, it works well enough).
> Mostly, it means using HTTP verbs on URLs to represent create/update/read/delete. (IE, POST/PUT/GET/DELETE)
Actually, REST has nothing to do with "using HTTP verbs". HTTP is a key part of the Web architecture by which REST was inspired (and HTTP/1.1 was itself designed to make the web more RESTful), but REST isn't dependent on a communication protocol -- indeed, REST used as defined is largely protocol neutral, and can even freely mix communications protocols.
> There are other intricacies like HATEOAS (which sounds like a horrible breakfast cereal), but it basically mostly comes down to updating resources using http verbs.
Using hypertext representations to transfer state is not just a peripheral "intricacy" of REST, it is central to it. That's why its called "representational state tranfer".
> (Personally I don't get the reverence it gets since it's basically just about verbs and locations, but whatever, it works well enough).
If you are going to reduce REST to a simple "its all about" statement, then "verbs and locations" are the wrong thing -- on that level, REST is all about resources and their representations. That's, again, why its called "representational state tranfer".
Insofar as it is about communications protocols at all, its about using them in a standardized manner not specific to the particular resources.
Actually, REST has nothing to do with "using HTTP verbs". HTTP is a key part of the Web architecture by which REST was inspired (and HTTP/1.1 was itself designed to make the web more RESTful), but REST isn't dependent on a communication protocol -- indeed, REST used as defined is largely protocol neutral, and can even freely mix communications protocols.
> There are other intricacies like HATEOAS (which sounds like a horrible breakfast cereal), but it basically mostly comes down to updating resources using http verbs.
Using hypertext representations to transfer state is not just a peripheral "intricacy" of REST, it is central to it. That's why its called "representational state tranfer".
> (Personally I don't get the reverence it gets since it's basically just about verbs and locations, but whatever, it works well enough).
If you are going to reduce REST to a simple "its all about" statement, then "verbs and locations" are the wrong thing -- on that level, REST is all about resources and their representations. That's, again, why its called "representational state tranfer".
Insofar as it is about communications protocols at all, its about using them in a standardized manner not specific to the particular resources.
No.
REST has nothing to do with HTTP. That is like saying that poetry has means using english to make sonnets that rhyme.
REST stands for representational state transfer. It is a software architecture style that sets up constraints on objects, and other data structures within a distributed network.
That is it. HTTP attempts to provide a way of doing REST, but you can even use HTTP to do things in a non-rest way.
REST has nothing to do with HTTP. That is like saying that poetry has means using english to make sonnets that rhyme.
REST stands for representational state transfer. It is a software architecture style that sets up constraints on objects, and other data structures within a distributed network.
That is it. HTTP attempts to provide a way of doing REST, but you can even use HTTP to do things in a non-rest way.
I think the reverence it gets is owed to people desperately wanting to follow a standard when it comes to offering an HTTP API. You want to make it as easy (=standardized) as possible to use it, and REST has emerged as a viable standard.
I think the ease of use isn’t just about being standardized, it’s also about being simple. REST (in)famously doesn’t support higher-level concepts like transactions neatly, but it provides the magic four database operations if you only need to work with a single resource at once, and for many applications that is sufficient.
REST is supposed to mean systems compliant with the architectural style defined by Roy Fielding in chapter 5 of his dissertation: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
Unfortunately, in popular programming it has become to mean anything and everything that uses resource-oriented URLs and at least loosely: HTTP methods as verbs to "operate" on those resources.
The misuse of the "REST" as a term, has required the creation of a new term: Hypermedia APIs: https://en.wikipedia.org/wiki/Hypermedia_API
Unfortunately, in popular programming it has become to mean anything and everything that uses resource-oriented URLs and at least loosely: HTTP methods as verbs to "operate" on those resources.
The misuse of the "REST" as a term, has required the creation of a new term: Hypermedia APIs: https://en.wikipedia.org/wiki/Hypermedia_API
Time and time again I've found the following classification useful for thinking about REST and web-APIs in general: http://www.nordsc.com/ext/classification_of_http_based_apis....
Most of the stuff people are describing here as REST would be classified as HTTP-based Type I/II according to the above resource.
Most of the stuff people are describing here as REST would be classified as HTTP-based Type I/II according to the above resource.
Kellabyte has the best explanation: http://kellabyte.com/2011/09/04/clarifying-rest/
So, at University, at the end of the course the students often create a project, and maybe a paper. A lot of these are pretty awful. Really. You can lookup a lot of them online to see. We'll wait.
Back already? That bad were they? Told you so. So, anyway, one of these awful papers somehow got far more attention from the web-tards then it was due.
As a result we cannot have a discussion about web and APIs without the church of RESTful dogma sticking in their two-penneth.
REST was and is a bad idea, but hey, it sells books, passing on the moronic tradition to the next gullible generation.
Sigh.
Back already? That bad were they? Told you so. So, anyway, one of these awful papers somehow got far more attention from the web-tards then it was due.
As a result we cannot have a discussion about web and APIs without the church of RESTful dogma sticking in their two-penneth.
REST was and is a bad idea, but hey, it sells books, passing on the moronic tradition to the next gullible generation.
Sigh.
While there are very confused and layered interpretations of what REST is, the reason it is important is that many of the Web Services APIs that preceded this trend used HTTP merely as a transport, but ignored so many of HTTP's features. This lead to them being difficult to use without bulky libraries. By using more of HTTP's features or basically HTTP as the API, it greatly simplifies and opens up possibilities and the tools that can interact with the API.
To elaborate a bit – after a lot of confusion and wondering, I came to the conclusion that REST is just a very poorly defined buzzword. Another conclusion was that it's ok – a good practice in fact – to combine REST and RPC in one API. (Specifically – use REST if you can, otherwise RPC.)
I personally define REST in two different ways, let's call them REST1 and REST2, short versions:
REST1
The API is a set of collections, for example we can have /articles and /comments. We can access individual items by /[collection]/[id]. The API can allow GET, POST, PUT, DELETE operations on both collections and items. Collections are filterable, you can do /articles?author=123 for example. Basically, this like a simple interface over a set of database tables.
REST2
The server has a certain state. The API is a set of views on that state. A view can be defined as a function without side-effects that takes the server state as an argument and returns something, usually encoded in JSON. Every view has a certain URL and can have GET, POST, PUT and DELETE operations allowed. The POST method is allowed only for a special type of view – a collection.
The second definition is more flexible. For example, /fulltextsearch?q=test or /multiply/3/5 would be completely REST2ful. But for some tasks, you would still need RPC, e.g. if you need to change the state in a non-trivial way.
I hope it's clear, if not, tell me.
I personally define REST in two different ways, let's call them REST1 and REST2, short versions:
REST1
The API is a set of collections, for example we can have /articles and /comments. We can access individual items by /[collection]/[id]. The API can allow GET, POST, PUT, DELETE operations on both collections and items. Collections are filterable, you can do /articles?author=123 for example. Basically, this like a simple interface over a set of database tables.
REST2
The server has a certain state. The API is a set of views on that state. A view can be defined as a function without side-effects that takes the server state as an argument and returns something, usually encoded in JSON. Every view has a certain URL and can have GET, POST, PUT and DELETE operations allowed. The POST method is allowed only for a special type of view – a collection.
The second definition is more flexible. For example, /fulltextsearch?q=test or /multiply/3/5 would be completely REST2ful. But for some tasks, you would still need RPC, e.g. if you need to change the state in a non-trivial way.
I hope it's clear, if not, tell me.
No, REST is not poorly defined, and there is no such thing as a "personal definition". It's not the word's fault that is has come to be abused as a buzzword. It's the fault of the people who abuse it.
Both your examples already fulfill many constraints of a RESTful design, but this makes it level 2 in the maturity model. So far, it's "only" an HTTP API, you need more to reach level 3, mandatory for REST. My points of critique:
1. That /[collection]/[id] thing or /articles?author=123 filter are only RESTful when the server advises the client how to construct the URI with a hypermedia control (e.g. HTML form or URI template, to name popular examples). Because you describe the URI, here, out of bound, it is a violation of REST.
2. I see a distinct lack of link relations between the resources you've named. Indeed, that should be the most prominent part of the description of a RESTful interface! What is the relation between articles and comments collections, or articles and comments items? Employ hyperlinks! Give the links types by coining link relations! (In actuality, don't be tempted to invent that particular wheel, because this model and its semantics are already well-defined by the Atom and AtomPub internet standards.)
3. "REST2" is not more flexible than "REST1", it's the same. Why? Because the HTTP spec already defines whether a method is without side-effects, check chapter §9. You also describe, here, out of bound, which method is applicable to which resource; that's also a violation, instead the server sends the headers Allow/Accept-Post/Accept-Patch, and the client ought to use the OPTIONS method to introspect a resource if it wants to know before trying blindly.
In your RESTful interface description, you should not repeat what is already covered by existing internet standards, concentrate on the things that are new in your problem domain.
Lastly, every RPC problem (a procedure is a verb, e.g. addFunds) can be modelled in a resource-oriented fashion (e.g. PUT /funds), where the nouns are the addressable resources, and the verbs are the HTTP methods. Okay, that was an stupid easy example, but it also holds true for more complex, see http://duncan-cragg.org/blog/post/getting-data-rest-dialogue... ff. If you are to become a talented API designer, you must recognise what the nouns of your problem domain are, and build the system's interaction around them.
Both your examples already fulfill many constraints of a RESTful design, but this makes it level 2 in the maturity model. So far, it's "only" an HTTP API, you need more to reach level 3, mandatory for REST. My points of critique:
1. That /[collection]/[id] thing or /articles?author=123 filter are only RESTful when the server advises the client how to construct the URI with a hypermedia control (e.g. HTML form or URI template, to name popular examples). Because you describe the URI, here, out of bound, it is a violation of REST.
2. I see a distinct lack of link relations between the resources you've named. Indeed, that should be the most prominent part of the description of a RESTful interface! What is the relation between articles and comments collections, or articles and comments items? Employ hyperlinks! Give the links types by coining link relations! (In actuality, don't be tempted to invent that particular wheel, because this model and its semantics are already well-defined by the Atom and AtomPub internet standards.)
3. "REST2" is not more flexible than "REST1", it's the same. Why? Because the HTTP spec already defines whether a method is without side-effects, check chapter §9. You also describe, here, out of bound, which method is applicable to which resource; that's also a violation, instead the server sends the headers Allow/Accept-Post/Accept-Patch, and the client ought to use the OPTIONS method to introspect a resource if it wants to know before trying blindly.
In your RESTful interface description, you should not repeat what is already covered by existing internet standards, concentrate on the things that are new in your problem domain.
Lastly, every RPC problem (a procedure is a verb, e.g. addFunds) can be modelled in a resource-oriented fashion (e.g. PUT /funds), where the nouns are the addressable resources, and the verbs are the HTTP methods. Okay, that was an stupid easy example, but it also holds true for more complex, see http://duncan-cragg.org/blog/post/getting-data-rest-dialogue... ff. If you are to become a talented API designer, you must recognise what the nouns of your problem domain are, and build the system's interaction around them.
I'm happy to read comments that indicate that understanding of REST is starting to improve. The old adage about sex applies to REST: "Most people that say they are doing it, aren't doing it. Those that are are probably doing it wrong".
It might be best to preface this with a list of things that REST isn't. Rest is not:
1. Pretty urls from your framework of choice that look like /dogs/breed/chow/weight/150 . Why? because the query string exists for a reason and has well defined semantics. 2. Using some framework serialization package to output xml or json for content negotiations. Why? because the hardest, most important part of REST is defining media types, and the garbage spewn by most serialization frameworks is not a clean media type. 3. Clients which access API's by curl'ing example.com/products/$productID are not restful. Why? because RESTful resources should be discoverable using hypertext. A client with a hard-coded url template is not a RESTful client.
REST, real REST, is a great architecture. In fact it's fair to say that the best example of RESTful architecture is the web you see in your browser. API's are usually a shallow copycat. What makes plain old html pages a poster child for REST? I'm glad you asked.
1. Hyper text. Guess what, JSON doesn't provide hypertext. JSON ootb is not restful. Certain standards on top of JSON (like the _link attribute) help bridge the gap. Our friends HTML and XML support hyper text. HTML in the standard way, and XML with the link attribute. If you're not using a content-type with well-defined semantics for links, you're not using REST.
2. Choices for intelligent UA's to browse or present as choices to their users. Forms provide a RESTful way to give a user a choice and allow them to manipulate or browser resources. JSON doesn't have anything like forms builtin. If I can't browse your "restful" API with my browser, you're not using REST.
the list goes on. But don't worry about it. Aside from not being quite as hip, it's perfectly ok if you're app isn't RESTful. Does your app provide a service that performs an action for the user? Maybe it's ok for that to be RPC. Does your app need to be tooling friendly for enterprise folks? It's ok to give them something SOAP related to make it easy for them to integrate their clients. Does your app do some sort of low-level file synchronization like dropbox? Then by all means run your service over HTTP so you can get through firewalls, but nobody cares if you pass back a list of binary identifiers instead of hyperlinks.
Really all that matters is that from a usability perspective, it's nice to make accessing your API easy, and HTTP is a great way to go if you want to lower the barrier to entry in using your API. Don't worry if your API doesn't use "hypertext as the engine of state" if it doesn't make sense for you. When you need to enhance your API, think of doing it the RESTful way first.
It might be best to preface this with a list of things that REST isn't. Rest is not:
1. Pretty urls from your framework of choice that look like /dogs/breed/chow/weight/150 . Why? because the query string exists for a reason and has well defined semantics. 2. Using some framework serialization package to output xml or json for content negotiations. Why? because the hardest, most important part of REST is defining media types, and the garbage spewn by most serialization frameworks is not a clean media type. 3. Clients which access API's by curl'ing example.com/products/$productID are not restful. Why? because RESTful resources should be discoverable using hypertext. A client with a hard-coded url template is not a RESTful client.
REST, real REST, is a great architecture. In fact it's fair to say that the best example of RESTful architecture is the web you see in your browser. API's are usually a shallow copycat. What makes plain old html pages a poster child for REST? I'm glad you asked.
1. Hyper text. Guess what, JSON doesn't provide hypertext. JSON ootb is not restful. Certain standards on top of JSON (like the _link attribute) help bridge the gap. Our friends HTML and XML support hyper text. HTML in the standard way, and XML with the link attribute. If you're not using a content-type with well-defined semantics for links, you're not using REST.
2. Choices for intelligent UA's to browse or present as choices to their users. Forms provide a RESTful way to give a user a choice and allow them to manipulate or browser resources. JSON doesn't have anything like forms builtin. If I can't browse your "restful" API with my browser, you're not using REST.
the list goes on. But don't worry about it. Aside from not being quite as hip, it's perfectly ok if you're app isn't RESTful. Does your app provide a service that performs an action for the user? Maybe it's ok for that to be RPC. Does your app need to be tooling friendly for enterprise folks? It's ok to give them something SOAP related to make it easy for them to integrate their clients. Does your app do some sort of low-level file synchronization like dropbox? Then by all means run your service over HTTP so you can get through firewalls, but nobody cares if you pass back a list of binary identifiers instead of hyperlinks.
Really all that matters is that from a usability perspective, it's nice to make accessing your API easy, and HTTP is a great way to go if you want to lower the barrier to entry in using your API. Don't worry if your API doesn't use "hypertext as the engine of state" if it doesn't make sense for you. When you need to enhance your API, think of doing it the RESTful way first.
You are right, and I also am glad that people come around from their earlier ignorance.
I wish to amend #1. There exists a clever hack that allows any media type to have hyperlinks. Let's take text/vcard as an example, it's a nice existing standard that can be used as representation for, say, a user. (Let's ignore for a moment that a special XML serialisation and the XFN microformat exists, so that the vcard semantics are embeddable into HTML.) It can be augmented with RFC 5988 Link headers:
I wish to amend #1. There exists a clever hack that allows any media type to have hyperlinks. Let's take text/vcard as an example, it's a nice existing standard that can be used as representation for, say, a user. (Let's ignore for a moment that a special XML serialisation and the XFN microformat exists, so that the vcard semantics are embeddable into HTML.) It can be augmented with RFC 5988 Link headers:
GET /user?id=123 HTTP/1.1
----
HTTP/1.1 200 OK
Content-Type: text/vcard
Link: </user?id=123>; rel="item self"
Link: </user?id=122>; rel="next"
Link: </user?id=124>; rel="prev"
Link: </user?id=1>; rel="first"
Link: </user?id=9000>; rel="last"
Link: </user>; rel="collection http://example.org/rel/foobar_users"
BEGIN:VCARD
VERSION:4.0
…
Teach a Dog to REST http://vimeo.com/17785736 is one of the best intros I've seen.
Everyone seems to have their own interpretation of what REST means, and that's exactly how you know it's not clearly defined. Not only that, but people are quite emotional about it too.
- Here's one way to look at it:
"REST" is a set of ideas on how to make
sensible web-applications.
- Here's another: "REST" is a meaningless buzzword
parroted by everyone and their neighbour's dog.The way I've always understood REST, it's all about having a rich vocabulary of nouns (resources), but a very limited vocabulary of verbs (basically only Create, Read, Update, Delete). So, in a RESTful version of this site, you don't 'upvote' a post (by which I mean call a remote procedure called 'upvote' with the post ID as an argument), you instead 'create an upvote' related to the post.
REST is an architectural style, a set of constraints applied to the design of a web API. An API can be considered RESTful if it satisfies ALL of the constraints.
The most commonly ignored/misunderstood constraint is that of Hypermedia As The Engine Of Application State. You can read more about the application of the term here: http://roysvork.wordpress.com/2013/03/13/why-im-giving-rest-...
The most commonly ignored/misunderstood constraint is that of Hypermedia As The Engine Of Application State. You can read more about the application of the term here: http://roysvork.wordpress.com/2013/03/13/why-im-giving-rest-...
Read the original paper, not blog posts. Roy Fielding in chapter 5 of his dissertation: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
REST is just a generally agreed upon convention that makes good use of HTTP verbs to create simpler URL structures when interacting with resources.
So basically, instead of having the following endpoints: site.com/create_user site.com/delete_user site.com/show_user site.com/update_user
You'd instead have a single use endpoint like so: site.com/user
And throw different HTTP verbs at it to signify the action.
It's definitely a well-defined concept and been part of Ruby on Rails since version 1.2.
So basically, instead of having the following endpoints: site.com/create_user site.com/delete_user site.com/show_user site.com/update_user
You'd instead have a single use endpoint like so: site.com/user
And throw different HTTP verbs at it to signify the action.
It's definitely a well-defined concept and been part of Ruby on Rails since version 1.2.