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 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.
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 :)
> 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.)
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
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.
I'd be interested to know what this site precisely checks for. Anyone got any ideas?
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).
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.
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.
* 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...
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.
That said, for getting started you can think as "resource" being a web-addressable representation of an object in your application.
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/"
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.
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.
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
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 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.
"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.
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.
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.
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.
{ "/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: hypermedia@librelist.com . That might be easier than checking HN history, and others can chime in too.
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.
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.
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.
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
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.
People don't do it right because pretty much every description is unintelligible (for example, most of the attempts on this thread).
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-...
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.
Most of the stuff people are describing here as REST would be classified as HTTP-based Type I/II according to the above resource.
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.'
http://martinfowler.com/articles/richardsonMaturityModel.htm...
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.
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
…
- 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.