Roy Fielding

Technically they're right, though; the textbook definition of REST is rare to nonexistent in my experience. What people do instead is create JSON-RPCs-over-HTTP APIs, sometimes following a REST-like URL scheme, and sometimes using different HTTP verbs on the same URL to perform different actions as one would in REST... but the API isn't really REST. The creator of REST has gone on the record multiple times about how you shouldn't call these APIs REST[0]. But in practice when most people say REST they just mean "JSON RPC over HTTP". I avoid calling things REST now and just use "JSON HTTP API" to avoid the "well, actually..." responses. (and yes, these APIs are by far the most common.) [0] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

> nor is "hypermedia" the only (or even main) design trait. If you take REST as what it’s original author defined, then it absolutely is. Fielding literally has an article saying so: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven > REST APIs must be hypertext-driven If you take REST as what it’s become (a worthless buzzword for HTTP-based APIs) then > REST is neither protocol-specific Is wrong in turn. You can’t deny both. Unless you’ve decided to make it even more worthless and just a synonym for « API » I guess.

> while REST is trivial. I'm not convinced of this -- or at least, we might use different definitions of "REST". The guy who created the concept of REST regularly (or used to regularly) call out common problems with "REST" APIs that make them more like RPC APIs that happened to be built on top of HTTP. For instance, [0]. Now, just because someone created a thing doesn't mean they had it right from the get-go. (For instance, the guy who named "gif" clearly pronounces it wrong.) But I've become convinced by Roy's points about what REST ought to be, and if "REST" is going to be meaningfully distinguished from "RPC", it's probably worth understanding his position. [0] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

You don't need PUT nor DELETE. It is OK to use POST[1]. Most people don't understand REST. It is not a standard, it is not a set of practices. It is an architectural style and the web is built on it. You can choose to follow the style (which is so much more than naming methods and URIs) or fight it. The dissertation is pretty clear about it[2], but most people ignore it because there are no code samples. [1]: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post (REST creator talking about the PUT misconception) [2]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm (Full REST dissertation)

I want to quote http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven : > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. If REST is to mean something useful then it should mean more than following the HTTP protocol. This stuff from the article is in the HTTP spec: > People have a tendency to route everything, including non-safe operations, through a GET. The Http Spec http://tools.ietf.org/html/rfc2616#section-9.1: > In particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe". I don't think "REST == Good" for all API's. In 2014! I think people who want to tell us about REST should know Fielding said.

That is a way to make non-REST API be more like REST. REST APIs must be self-describing from the start. Those kinds of responses should be sent for GET requests! This is a must-read clarification from Roy, as most "REST" APIs are less RESTful than HTML pages built on top of them: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

I posted this on the original article but I might as well post it here as well, with bonus typo corrections. The question is if XMPP can be made into an efficient application for streaming events to multiple (or multitudes of) subscribers. Chat is a 1-to-1 limited tima affair. PubSub is not. I am afraid this is not simply a matter of a bette rimplementation of an XMPP server but something much more fundamental. Roy fielding has argued (http://roy.gbiv.com/untangled/2008/paper-tigers-and-hidden-dragons) why the economics of XMPP for pub/sub do not work out and why the solution is simply to better structure the HTTP APIs that the various services provide. This is why large customers are needed. There is cost involved and somebody has to pay it. The recent Twitter/Gnip moves serve as testament to Roy's foresight.

Re: https://johnholdun.com/apis/rest/ > When I say “REST,” I don’t mean when to use GET vs. POST (although that’s also important). What I mean is that you should read Roy Fielding’s dissertation, Architectural Styles and the Design of Network-based Software Architectures, where Representational State Transfer was coined. Not once in its definition does he mention HTTP verbs! Something that I still don't understand, is how HATEOAS relates to OpenAPI spec. Quoting Roy T. Fielding himself (https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven… > API designers, please note the following rules before calling your creation a REST API: > [...] > A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling]. > [...] > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API).…

> URLs generally have less protection than a password That's an understatement. Passwords are supposed to be private by design. URLs are not. > because that's how we design a lot of our systems (and this is a property of our systems and not of the URLs themselves) That's simply not true. URLs don't have protection because the notion of a private URL is a flat-out contradiction. As I said before: it goes against the fundamental design of the Web. URLs are not in any sense designed to be private. Like, at all. If anything, they are designed not to be private. URLs are by their nature public information[1]. Anyone who believes or wishes otherwise is someone who believes or wishes that the Web is something other than the thing actually proposed, designed, and implemented. Anyone can, at their own peril, try to devise other higher-level systems that exploit implementation details and other incidentals in non-normative ways while trying to justify it on the basis that it jibes with what you have observed in practice. You are also free to design a content-protection scheme that hinges on the whitespace in the client request varying just so, or where the HTTP heADEr naMEs follow a suPEr seCREt caPITALIZATIOn coNVENTIOn, etc. But no one else has any obligation to conform to the expectations necessarily prescribed by those lame designs nor to commit themselves to any action/inaction implied. "Leaking URLs" is a non-offense. 1.…

> Oh wow, you seem to have come out of reading this blog post still extremely confused. Yea, guilty of not reading the article properly sorry. I now get what you are saying about not using the status to drive what forms appear in UI / actions can be performed. Using JSON-ld you might use the https://schema.org/potentialAction property to describe what actions the resources allows which provides the equivalent information as the HTML form tag. After reading Roy Fielding's blog a bit I do find my understanding of REST to be lacking. My reading of the principles agrees with your statement: "It displays the hypermedia without knowing semantics at all" but then he seems to also endorse RDF and N3 which are more like JSON-ld from my understanding and I'm not sure how they cater to display purposes. > When representations are provided in hypertext form with typed relations (using microformats of HTML, RDF in N3 or XML, or even SVG), then automated agents can traverse these applications almost as well as any human. There are plenty of examples in the linked data communities. More important to me is that the same design reflects good human-Web design, and thus we can design the protocols to support both machine and human-driven applications by following the same architectural style. https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

> I see it being called an overload, but I see no alternatives.. Some APIs make rather poor use of HTTP, using it as a glorified RPC mechanism. Done poorly, this can make caching hard or impossible. A fair number of self-proclaimed "REST" APIs seem to do okay on the HTTP verb part of things, using GET/PUT as HTTP intended, but they insist on naming resources by "IDs" or something, and to then fetch the named resource, require the user of the API to manually construct the URL themselves. This is antithetical to what Fielding's REST proposed, which is that the URL serves as a universal mechanism for naming resources, and that end clients don't need to know anything about how to construct URLs, because they can just follow the one they are given. (And the server can do whatever it wants with URL layout.) Fielding himself notes this on his blog[1], > A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). For practical examples of this, the Azure API is significantly hit or miss here. Some references to other resources are in URI-references (this is a good application of REST) but sometimes it is just a string name and you have to know, out of band, how to construct a URL to that resource. I'd recommend the ACME API as the best application of REST that I am aware of. [1]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

This is an oft revisited topic, and it might be worthwhile to cite a few paragraphs from Dr Fielding in order to support and expand upon the submitted article. "Search my dissertation and you won’t find any mention of CRUD or POST." [0] > For example, some APIs may need to support actions such as submit, approve, and decline. With our somewhat limited action verbs in HTTP, how can we add this to our API? By representing the difference in states. Or otherwise. The communication medium is not the API. ("A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. " [1]) > POST /articles/{articleId}/publish , POST /articles/{articleId}/submit , ... etc. A few years ago I was zealously advocating against representing actions in URIs, and using a generic /actions [sub]resource, but this actually makes it simpler to represent the available actions to the client. And sure, this can be thought of as REST via the code-on-demand part of the architecture. The server points to a script (it doesn't have to be JS, but the media type must be defined in the REST API), that can understand the available actions from the state representation, and construct the necessary representations for the desired actions. (So in a HTTP API, the JS interprets the JSON and knows how to put together POST requests to modify the resources, without the actions having been…

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…

> People right on HN spend their time arguing over what is restful and what isn't ,because vague "semantics". The defined semantics of HTTP/1.1 methods (REST is a style, but HTTP/1.1 is a standard) are not vague. > And to be frank, if you're not using HATEOAS , there is very little difference between a api with beautiful urls and a few headers and rpc. If you aren't using HATEOAS, you aren't using REST. That doesn't necessarily mean that it is indistinguishable from RPC. > The original spec is brilliant yet way to vague to be useful. What original spec are you talking about? > RPC isn't HTTP, Neither is REST, though HTTP is itself an example of REST and a protocol which is fairly convenient for use in REST services. > which is totally handy in the context of micro-services as one can implement RPC over any protocol. that's not the case for Rest... > On the contrary, it is rather central to the point of the REST architectural style that you can implement it over any protocol (or, given hypertext formats which support identification of different protocols, over any combination of protocols simultaneously.) From the creator of REST [0]: A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that…

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-hypertext-driven http://isitrestful.com/

> REST Hooks itself is not a specification, it is a collection of patterns that treat webhooks like subscriptions. Bummer. No matter if you like it or not, a collection of patterns with a name _is_ a specification, just possibly a poorly defined one. See the confusion in this thread. If it were a link to a spec, nobody would be confused. > Skip the pedantic arguments about standards and implementation details This reads to me as "everyone is going to have a slightly incompatible implementation. One library wont be good enough, I'll need to write a new one per site that uses this." Furthermore, what about PubSubHubbub? Finally, polling is great: Ive found few situations where it doesn't work well, people just tend to only do the most basic of implementations and blame polling. See http://roy.gbiv.com/untangled/2008/paper-tigers-and-hidden-dragons for a really interesting example. EDIT: numbers were real, added a supporting link

Sorry, but it lacks the most misunderstood parts of REST: - Hypermedia as the Engine of Application State (HATEOAS) - Returning concrete mediatypes (standard is great, custom is OK) instead of generic 'application/json' or 'application/xml' It also contains some misunderstandings: - Sending a sha1 of the password to the server is bad, for two reasons: - - First, and more importantly, if you send the hash of the password over the wire, the hash becomes a plain-text password! Seems strange? Think about it: if the attacker somehow gets the hash, he can just use it as-is to authenticate to your API - he doesn't need to crack it. If you're using HTTPS, just use Basic Auth. Otherwise, you should implement (read: use a library!) proper request signing. - - Second, sha1 by itself is pitiful - it can be cracked in mere seconds. Use bcrypt (this, on the server). Once you know the top level objects and actions in your product, designing the endpoints becomes easier and clearer. For example, to “add” a new venue, you would probably have to call a method similar to /venues/add Sorry, but no, no. In REST, there should be a single endpoint. Everything else is done by navigating. And in REST, there are no method calls! As Roy Fielding would say, this screams RPC! To add a venue you should just POST to /venues/ (URL which you discovered by navigating the API). Read his blog post with some of the rules that make a REST API:…

> Of course not, nobody thinks that. I'm pretty sure Fielding does, see "improved on-the-fly": "The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand)." http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven Hypermedia is great for intelligent clients (e.g. humans) who can adapt to, say, a webpage changing and new fields suddenly showing up in the hypermedia (HTML) that are now required. However, for an application, it's going to be hard-coded to either do: 1) POST /employee with name=foo&age=1, GET /employee?id=1 Or 2) GET /hateoas-entry-point, select "new employee" link, fill out the 2 fields (and only 2 fields) it knew about when the client was programmed (name, age), post it to the "save employee link", go back to "/hateoas-entry-point", select "get employee" link, fill in the "id=1". (...or something like that). In either scenario, the non-human client is just as hard-coded as the other--it's either jumping to external URLs or jumping to internal links. Either way those URLs/links (or link ids) can't change and the functionality is just as frozen. Perhaps the benefits of hypermedia would be more obvious if Fielding built a toy example or two that we could all touch and feel instead of just dream up. But so far there seem to be a lot of non-HATEOAS REST APIs that are doing just fine sans hypermedia.

I will bet money that most of these "RESTful" APIs are nothing of the sort. In almost all cases, when somebody says they're using REST, they're actually using ad-hoc XML-RPC -- fixed URLs, non-descriptive content, etc. Ignorant programmers have fixated on trivial aspects of some REST applications (use of PUT/DELETE, "pretty" URLs) and ignored all the important aspects. This sort of thing happens a lot in software culture -- see people claiming Java or C# are object-oriented, that C++ is functional, that Python or LISP are "scripting languages". It's cargo-cult nomenclature, and it disrupts technical conversation to the point of uselessness. Roy T. Fielding, who described the REST style, has an excellent blog post titled REST APIs must be hypertext-driven < http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven >, where he lays out some ground rules for calling any given interface a REST API.

Actually, I think best practice is to not put the version number in the URI at all. Instead versioning should be handled via content negotiation. That is to say, a client specifies the type of resource they want back via the Accepts: header, and that resource is versioned. So A request would look something like: GET /client Accepts: application/vnd.clientlist.v1+json And they would get back the version 1 client list response. If they want v2, etc, they can specify a different content type (clientlist.v2+json, etc). Also note, that putting verbs in your URIs is counterintuitive. The verb for a REST operation is the HTTP method (GET, POST, PUT, DELETE). The URI should simply represent the resource being retrieved. An argument can be made that the client list is the resource, but in reality listing things from a REST API is a first class concept and shouldn't need separate URIs. It's simply a request for a specific resource type without qualifying it by asking for a single instance of that resource. So, GET /client would return all clients (can add query parameters for pagination, etc), GET /client/834 would return a single client resource. See also: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Schema Discovery Service is interesting but I have been wondering whether it is finally time to start implementing HATEOAS[0] in REST services. [0] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

> Take some ordinary, off-the-shelf servers. Treat them as dumb, untrusted pipes. Sounds like REST. The original REST, not the botched CRUD that companies pushed for. https://roy.gbiv.com/pubs/dissertation/fielding_dissertation.pdf > The combination of layered system and uniform interface constraints induces architectural properties similar to those of the uniform pipe-and-filter style. See also Figure 5-8. The dissertation is all about deriving that network style.

> there was a type of person in the 2000s era who insisted that APIs were not truly RESTful if they weren't also hypermedia APIs The creator of REST, Roy Fielding, literally said this loud and clear: > REST APIs must be hypertext-driven > 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. — https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven I think of all the people in the world, the creator of REST gets to say what is and isn’t REST.

HATEOAS is crucial to what [Roy Fielding](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven… calls REST APIs. >A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. Most APIs that people call "RESTful" -- regardless of whether they come with an OpenAPI spec -- don't obey HATEOAS. A typical OpenAPI spec describes the possible request paths and verbs. However, you probably wouldn't be able to discover all that information just by starting from the entry point and parsing the `hrefs` in the response bodies.

If you need to request multiple REST resources for a single "operation", then you don't have enough REST resources defined. [1] Just make another endpoint for getting the whole thing in one go and call it a day, don't try to overly generalise your API. Going even further, your server requests to the database could be similar as well, one query to get everything needed, then you don't even need to worry about server to database distance! [1] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven…

Roy Fielding has entered the chat. https://en.m.wikipedia.org/wiki/Representational_state_transfer https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Have a read of The Rest of REST -- Roy T. Fielding (2007) https://roy.gbiv.com/talks/200709_fielding_rest.pdf

REST is almost always a misused term: https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest… HATEOAS (or the hypermedia constraint) is a requirement for a REST-ful system, as the creator of the term (Roy Fielding) says here: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven I have an rewritten wikipedia article on HATEOAS here: https://htmx.org/essays/hateoas/ And I agree it doesn't make much sense outside of a hypermedia system (like the web), being consumed by humans: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html

"...REST JSON API..." Please update. https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Not in the eyes of its creator https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven