Not sure about your karma sacrifice, but if someone has doubts:

  > What needs to be done to make the REST architectural style clear on the
  > notion that hypertext is a constraint? In other words, if the engine of
  > application state (and hence the API) is not being driven by hypertext,
  > then it cannot be RESTful and cannot be a REST API. Period. Is there
  > some broken manual somewhere that needs to be fixed?

That's by Roy T. Fielding himself (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...)

So if it is not HATEOAS it is not REST. Alas, I am not aware about any term which can be used for these Richardson maturity model Level 2 services.

It reminds me that GIF is pronounced GIF by most people even if the inventor pronounces it as JIF.

The language is what people use to communicate. REST may mean whatever most people think it means regardless what the inventor of the term thinks it should mean.

Another example is the word hacker. For most people it is "a person who uses computers to gain unauthorized access to data" (according to Google) that is different from the meaning used on this site: "one who works like a hack at writing and experimenting with software, one who enjoys computer programming for its own sake" http://www.etymonline.com/index.php?term=hacker

Thank you for that quote, I shall save it for future use.

Also lots of replies and 0 points. That's what I'm talking about, this always gets downvoted.

REST seems like an elephant in a room with some blind folks. Everybody who touches it thinks it's something different than the next guy, and they're all describing only one element of the thing.

That said, I don't actually know what this elephant looks like, either, because everybody I've read on the subject seems to have only a partial understanding of it...thus, I have a partial understanding of it.

If you know what the whole elephant looks like, and have good resources for what makes something actually REST, I'd be interested.

The best way to understand REST is by example. First check out the blog post by Roy Fielding mentioned in this thread which summarizes the constraints [1]. Then let's examine how several popular restful services work versus those constraints.

Here are some popular well-known services to use as examples: Google.com Amazon.com Facebook.com News.ycombinator.com.

- You enter these services through the site root with no prior knowledge about the services aside from standard media types (HTML/CSS/JS)

- Hypermedia is the engine of application state – meaning that you load a webpage a.k.a. resource that contains hypermedia links to other resources, and you navigate between states in the application by following those hypermedia links. For example, the hacker news homepage contains links to news articles and comment threads about them, which contains links to reply to those comments, and so on.

- The application describes how to compose requests using standard media types such as web forms and JavaScript. Because the pages instruct the client about what requests to compose and to which URL, the services have control over their own name spaces which have no fixed resource names or hierarchy.

I consider REST to be most easily understood as a departure to application protocol design prior to the Web, where each application and service had a unique and custom binary protocol, and a client for these services had to be reprogrammed to interact with it. REST is a set of constraints for designing services that run at Internet scale and that highly decouples clients and servers. Fielding's thesis on REST has more detail on the principles by which the REST architectural style was derived.

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

The big problem with using the hypertext Web as an example of REST is that there is a human operator literally driving that "engine of application state". Most API clients cannot afford to compute their state transitions on a network of 80 billion neurons.

REST is a human driven protocol. That's why resources have a link to a description of what the resource is.

Are you suggesting that Fielding did not intend REST to be used in automated systems?

By "distributed hypermedia systems", did he really mean "alternative browsers for alternative WWWs"?

I can't adequately convey what I think is Fielding's position on how machines should interact with RESTful systems, but I will convey my understanding of the purpose and intent of his thesis:

REST is a characterization of the Web architecture itself. It's not an alternative WWW, it is an abstract description of the principles behind the WWW. You can see this theme in Chapter 4 of the thesis in which Fielding characterizes REST [1].

> This chapter presents the requirements of the World Wide Web architecture and the problems faced in designing and evaluating proposed improvements to its key communication protocols. I use the insights garnered from the survey and classification of architectural styles for network-based hypermedia systems to hypothesize methods for developing an architectural style that would be used to guide the design of improvements for the modern Web architecture. [...]

> The early Web architecture was based on solid principles--separation of concerns, simplicity, and generality--but lacked an architectural description and rationale. The design was based on a set of informal hypertext notes, two early papers oriented towards the user community, and archived discussions on the Web developer community mailing list. In reality, however, the only true description of the early Web architecture was found within the implementations of libwww (the CERN protocol library for clients and servers), Mosaic (the NCSA browser client), and an assortment of other implementations that interoperated with them.

> An architectural style can be used to define the principles behind the Web architecture such that they are visible to future architects. As discussed in Chapter 1, a style is a named set of constraints on architectural elements that induces the set of properties desired of the architecture. The first step in my approach, therefore, is to identify the constraints placed within the early Web architecture that are responsible for its desirable properties. (internal citations elided)

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

Yes, they can be used by automated system but the automated system was developed by humans who explored the RESTful service.

No there isn't, a great deal of the web is loaded without direct human requests. For example:

* Web crawlers

* Archival services

* Embedded resources (stylesheets, JavaScript, images)

* Newsfeeds

All those examples are hard coded algorithms in the bulk copy category. They pretty much just use the GET method to download all or a specific subset of a site.

To truly drive a REST API requires a human or an AI. The AI doesn't need to be human equivalent, just smart enough to inteligently interpret the hypermedia. If the API changes the AI would be able to adapt.

I'm talking about the complexity of the computer on the Enterprise in ST:TNG. You give it a command and it figures out how to go about solving it.

You don't need an AI. A client for automated interaction will hard-code assumptions about content rather than URIs. If the client cannot find a link inside a document, it should just throw an error. A good service would keep links as long as possible, even when deprecated or provide redirects to new resources.

A client for human interaction though (like a native application or a SPA), can just implement the visitor pattern to display the UI.

Instead of moaning about the architecture principles, we must implement solutions / examples of how to write good clients against REST-based services!

I don't know where you got the idea that REST needs futuristic AI, and you haven't really explained why you think that way.

Why does a REST client have to intelligently interpret the hypermedia? Why are hard-coded algorithms a problem? Why does it need to adapt to changes in the API? None of those things are requirements for REST, you've inserted them for seemingly no reason.

For instance, consider an unattended webcam you want to use to show off, e.g. the growth of a flower bed remotely. It has the URI for a web service that returns a resource describing actions it can take:

    {
        "actions": [
            {
                "rel": "report-problem",
                "href": "https://example.com/report-problem",
                "method": "POST",
                "accept": "application/problem+json"
            },
            {
                "rel": "update-frame",
                "href": "https://example.com/update-frame",
                "method": "POST",
                "accept": "image/*"
            }
        ]
    }

The definition of the report-problem relationship is "This is the action to take when an error occurs."

The definition of the update-frame relationship is "This is the action to take when a new frame is available to upload."

This API defines one media type and two relationships. It requires no futuristic artificial intelligence or human intervention, it just needs to speak HTTP, parse simple JSON, and trigger the actions based on simple conditions.

It also doesn't provide much benefit over a plain RPC-like interface, because, for practical reasons, the webcam will be coded to send requests directly to https://example.com/report-problem and https://example.com/update-frame (the "bookmarks"). If you want to change those URLs, your best hope is that the webcam will understand a 307 or 308 redirect.

RPC vs REST is an entirely different argument. We're talking about REST best practices here, not "let's do RPC instead".

There's no reason for the webcam to hard-code URIs, and that's a violation of the architectural constraints. Just arbitrarily deciding to disregard facets of the architectural pattern without giving a reason does not add to this discussion.

None of this relates to whether or not you need futuristic AI or human intervention. I think from the example, it's pretty clear you need neither for a REST API.

> We're talking about REST best practices here, not "let's do RPC instead".

I don't think so. Avernar above seems to argue against REST as an architectural style (RPC being the default as everybody uses it). I thought you were trying to defend REST with your example, and I wanted to point out a weakness in that example.

> There's no reason for the webcam to hard-code URIs, and that's a violation of the architectural constraints.

The webcam has to hardcode some URIs (entry points). Consider that it could be using other services: perhaps a social network to post updates on. Then it must hardcode another entry point URI. But at that point -- and since every resource is supposedly independent and only explicit relations matter -- why can't the webcam treat the "problem report service" and the "update frame service" as two entirely separate services to hardcode? Which constraint of REST does this violate?

In your example, insisting that the webcam go through the entry point doesn't even buy the server a lot of flexibility. You reduce the client's knowledge from 2 URLs to 1 URL -- a URL that you may still want to change etc.

An extra HTTP roundtrip every time can well be an unpleasant overhead. HTTP client caches are sparsely supported and notoriously complex (RFC 7234 is 41 pages long). Rolling your own cache is, well, rolling your own.

And then there is the human problem. I was blown away by a discussion [1] where people reported using cryptography to prevent in-house clients from hardcoding URLs. I was also saddened when I read the JSON API spec [2] -- a great example of REST, I think -- only to discover that most existing implementations [3] disregard the linking aspect and hardcode the URL structure that the spec uses for examples. But this is not a complaint against your webcam example so much as it is a general hurdle with REST.

[1] http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-ha... [2] http://jsonapi.org/ [3] http://jsonapi.org/implementations/

> None of this relates to whether or not you need futuristic AI or human intervention. I think from the example, it's pretty clear you need neither for a REST API.

Absolutely.

True, and some of these use cases are very interesting.

jcrites does not mention them, though. I realize now that his comment does not preclude them, either, but still this example would be more convincing if automated clients were emphasized, because that is what most people are actually building and care about.

I suggest you go to the original source, ie, Roy Fielding:

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...

http://roy.gbiv.com/untangled/tag/rest

https://www.infoq.com/articles/roy-fielding-on-versioning

I was going to post the same. I was lucky enough to get a few answers from Fielding himself when I first started learning this.

This is the video that made it finally "click" for me. https://vimeo.com/20781278

We don't yet have the abstractions, libraries, conventions or standards for this to work fully yet, but we're close.

> REST seems like an elephant in a room with some blind folks. Everybody who touches it thinks it's something different than the next guy, and they're all describing only one element of the thing.

I don't see it that way at all. Sure, there are minor quibbles about various approaches, but you can easily place everybody into one of two camps: the ones who don't know/care about REST's technical definition, and the ones that do. The two groups largely agree about what REST is amongst members of their own group, but disagree with the other group.

I think the above commentor got it right. You map the CRUD actions to HTTP verbs and statuses, as many of them make sense for your API, with links to further resources along the way.

> or any way of discovering features of an API programmatically.

So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice? I mean really, how do we normally consume APIs? We read the docs to figure out which endpoints we need to call, call them in the right order, and do the right stuff with the result. Nothing about that process is automatic; it takes a human to figure out what's available and the right way to use it.

To me the hypermedia part of REST has always seemed like a pointless academic exercise. Yes it's really cool to be able to point a service browser at your service's root resource and have it map the whole thing out but in practice, when is this ever anything but a neat party trick?

> So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice?

For the type of systems REST is designed to address, all the time. Its not just random happenstance that REST was articulated in the context of an existing, well-known, widely-used system of that type (the WWW.)

Arguably, many API designers are neither designing the kind of systems REST is intended for nor designing things for which their priority is for them to be well-behaved components in a distributed system that, taken as a whole, is the kind of system REST is intended for. Which is fine, but then there is little reason to use REST and less to use pretend-REST.

Efforts like the Hypertext Application Language (HAL) [1] are attempts to implement HATEOAS.

The point that's often missed in casual discussions of REST is that 'link relations' are extremely important, because they represent well-specified ways of relating one resource to another. They are as critical to REST as mediatypes (MIME types) are.

In the graph theory sense, link relations are the label on an edge, URIs are the nodes, and mediatypes are formats that can be used as concrete representations of the nodes.

The IANA maintains a Link Relations registry [2].

[1] http://stateless.co/hal_specification.html

[2] http://www.iana.org/assignments/link-relations/link-relation...

It means being able to:

- Never write a "client" again, use your "REST" library and then just traverse relationships and call actions, rather like an ORM or having a local object graph. - Letting the API provider optimise your usage, by providing different data at different times, inlining at different times, etc, without any changes to your code.

I don't know why everyone wants to downvote this comment. It's absolutely right.

I would add that REST has nothing to do with pretty URIs, JSON formatting, versioning, query strings, and more misconceptions that people seem to mistake for the architectural style. There is nothing that isn't RESTful with URIs like "/a89f30e9" instead of "/:type/:id". Even TBL thinks URIs should be opaque: https://www.w3.org/DesignIssues/Axioms.html#opaque

To be frank, main issue is people are arguing about semantics, one side thinks Fielding's definition is the only thing that can be called REST, and the other larger(?) side could care less about that academic definition and are describing some simple rules for HTTP APIs. While it would be nice if there were two terms, just saying "This is NOT REST" really doesn't clarify anything.

I'm fine with APIs continuing to be disparate systems if they have a simple, sensible design and have comprehensive documentation. Let's just stop calling them "REST" since they're not as you've pointed out.

Why not push for them to become something more? Documentation for humans is good, but you know what's better? Documentation for computers so that we don't have to build integrations anymore!

I would love to see how this could be realistically done. I recall this being attempted with WSDLs, but there was still a ton of man hours required to integrate with an endpoint.

There is still always an impedance mismatch between the server representation and what the client representation that needs to be fixed.

Like ORMs, such integration automation will always be, at best, a leaky abstraction that makes the easy bits easier, and the hard bits harder.

I'm not sure the point about the ORMs is entirely true. I see what you're saying, but the API boundary should be the canonical definition (unlike an ORM where the database might be), and the server and client need to conform to that, so there shouldn't be leakage.

No worries. There are people out there, like me, who agree with you. You have my vote on this.

Lets say Microsoft at least created their own format, that allows some discovery. That is a good approach, because a big upfront design can be harmful. There are few decisions in HTML you can take as an example.

I am currently working on having a format for my company, that is based on Siren. Its no easy thing to do, because I want it to be easy to be used (which is not simple).

There are degrees of completeness and this expands on the REST standard by a whole lot more.

Frankly I would prefer adhering to this standard.

Any shining examples you'd care to share?

Agreed, and specifically:

> APIs will continue to be a disparate system that requires custom code for every integration until we can embrace the full benefits of REST

Have an example of a client that DOESN'T require custom code to use an API?

I think this entire debate is summed up best by:

> There is no magical "smart client" that somehow knows that rel=comments means that the link leads to comments about the current resource and can figure out it should POST there to create a new comment. It has no idea what the hell a "comment" is. [1]

[1] https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/

This is pretty much the crux of the problem that the Semantic Web / Linked Data folks have been working on for years. They have the technology to do it (RDF). This technology is not widely used for a number of reasons, but "because it can never exist (and I'll write that in boldface for extra credibility)" is not one of them.

People have been able to agree on many common vocabularies of stuff, like "<h1>" and "<svg:ellipse>" and "rel=pingback", and have it work more or less. It is not absurd to suggest that such an agreement can be achieved -- to some extent -- in APIs.

The thing is, those servers and clients already exist, people are just to tied to their notion of "API" to see them. And in fact, you used them to post that very comment.

A website is a RESTful service which a generic client can interact with despite not having any custom code. Does it do so by magically understanding what an <a> or <img> tags are or by magically decoding PNG bytestreams? No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed.

> No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed.

You're correct.

But that's not what we're talking about. We're talking about a web browser that can understand its posting a Comment, not a form (or a random collection of key-value pairs). The primitives that make the web work are quite different from the high-level concepts that make an application work.

My browser understands how to display links and forms and text and graphics. It does not understand how to display a comment or a user account or the number of votes a comment has, let alone know when I'm allowed to vote up or down, understand the relationship between a user account and a comment, understand a comment being owned by my user account or another, etc, etc.

What exactly is the end goal? That a HATEOAS-style REST API can be created, you can go to some entry point with your browser, and with no one writing any UI code it just understands how to render the Hacker News site? It will magically understand that the main page contains a list of articles, those articles have comments, links to an original source, etc?

This is my understanding of the goal of HATEOAS. If that's not the goal, I don't understand what it gets besides being a way to build a tiny part of documentation necessary to consume an API.

> Have an example of a client that DOESN'T require custom code to use an API?

Your web browser.

Right here. It's talking with HN's API for me to let me post this comment.

Whenever you have an URL that responds to the browser's requests to let the user do something, that's an API. Maybe a shitty, ad-hoc, poorly designed one, but it's an API. You can even write custom code against if if you want to.

> Your web browser.

My web browser isn't interacting autonomously with HN. It has a human driving it.

No clients know that "comments" means Comments, because no one has standardised it yet. There's no reason that we can't define "rel=comments" as being the comments for something, in the same way that https://schema.org/ has defined schemas for a range of taxonomies on the web already.

I don't have an example of a public API that can be used by a generic client because no one is making them. I've played around with them in a few projects and there are rough edges, but no reason we can't move forward to them. Google already use 'real' REST for some of their mobile apps as far as I can remember.

So all this push to "do it right" and HTATEOAS, is not actually meant to provide immediate benefit? It is only meant to help enable benefit in the future, when everyone is on board, and the usage of "rel" in json responses is agreed upon?

> No clients know that "comments" means Comments, because no one has standardised it yet.

Given that 'Comments' on HN are different than comments on Facebook, comments on a sales invoice, comments in a threaded forum, and comments on a pull request, how will this get standardized? On their face they may have relatively similar goals, but they have different semantics, rules and ways of being displayed.

On top of that, what happens when I create a new application, with a new object concept that's not standardized? Do I have to wait for it to get standardized and implemented in this magic client before I can launch? Or do I have to build a custom client anyway, entirely negating the point of using standardized stuff in the first place?

It's conceivable that with enough effort, some client could understand the semantics of all object types that are contained in a standard, and the standard is big enough to cover ever situation ever possible.. But then what? Who wants to build an app that basically looks and functions identically to your competitors (who are all using the same semantic objects)?

> There is no magical "smart client" that somehow knows that rel=comments means that the link leads to comments about the current resource and can figure out it should POST there to create a new comment. It has no idea what the hell a "comment" is.

Yes there is: that client is a human being. The point of REST and HATEOAS is to write something that works properly for humans, and to which general software can specifically be adapted.

That's part of why I loathe single page apps and JavaScript so much: HTTP & HTML already offer an incredible expressive range, and JavaScript just tramples over the forms and scaffolding they create.

The JSON API spec is pretty good: http://jsonapi.org/

Search for "rest api standard" you will find a bunch.

While I like standard, and I am always an advocate of standard, I also don't agree with standard body's decision on the exact format. This is the challenge. HATEOS is an absolutely great idea, but also painful to implement, making payload larger. One question I ask is "how many kinds of resource links do I need to supply?"