Roy Fielding

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…

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).…

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…

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

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

> 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.…