GOTO 2014 • REST: I don't Think it Means What You Think it Does • Stefan Tilkov

By: GOTO Conferences

325   14   37726

Uploaded on 10/10/2014

This presentation was recorded at GOTO Amsterdam 2014

Stefan Tilkov - SOA & REST Authority, innoQ Founder

These days, REST has become truly fashionable. No matter what system, product or service we look at, everything claims to offer a "REST API". But as is often the case with technical concepts that gain acceptance, many instances just stick the label on something that really doesn't meet expectations. [...]
Download slides and read the full abstract here:'t%20Think%20it%20Means%20What%20You%20Think%20it%20Does

Comments (9):

By anonymous    2017-09-20


  • REST is an architectural style (repeated for completeness, you seem to be clear on this point).
  • The World Wide Web is a reference application, which (mostly) demonstrates that architectural style.
  • HTTP is one of three "core" technologies in the web stack.

I don't find a clear difference between HTTP and REST then if REST is implemented based on HTTP.

The short answer is that HTTP alone is not sufficient.

Jim Webber (2011)

HTTP is an application protocol whose application domain is the transfer of documents across a network.

We had applications to transfer documents across a network prior to HTTP -- file transfer protocol, gopher, wais... all of which had negligible penetration into the general public. In contrast, the web was catastrophically successful; it was the killer app of the internet.

Fielding's thesis -- in particular Chapter 6: Experience and Evaluation -- is, among other things, an exploration of the question "why was the web so successful?" with emphasis on the architectural constraints that protected the induced properties of the web.

In 2008, Leonard Richardson introduced his maturity heuristic for evaluating web services.

[URI + HTTP + HTML] form a technology stack for web services. When people design a web service they tend to pick some technologies from the bottom of the stack. You can judge them crudely by seeing whether they pick zero, one, two, or three technologies.

When I say you pick from the stack I don't mean that you'll ever find a web service that doesn't use HTTP at all or that has no URIs. I mean there's a class of web services that doesn't really get URIs or doesn't really get HTTP. If your REST radar is finely tuned you sense there's something wrong with these services, and you can talk about violation of the RESTful constraints, but it's kind of a bloodless way to talk. It's not clear why anyone should care.

These technologies don't implement poka-yoke. Which is to say, the technologies don't force you to use them completely, correctly, or to best effect.

Ian S Robinson covered similar ground in his 2010 talk The Counterintuitive Web.

In the talk I described how we can implement rich and interesting business processes in (RESTful) Web applications, but only if we think in terms of protocol resources, not coarse-grained domain resources. By embracing the Web as first and foremost a web of data, an open set of resource representations manipulated in the same-old-same-old ways using a closed set of verbs, our designs capture the behaviours most CRUD-based, data-centric applications so sorely lack.

This slide, taken from that talk, illustrates three different resource designs:

three examples of resource designs

You can do all of these on HTTP, the protocol standard does not constrain you.

The design at the top of the slide has an RPC character: the business protocol is executed by sending many different messages to a single endpoint. Participation in the business protocol is limited to those components in the conversation that recognize this particular interface; in short, you can't achieve scale with out-of-the-box standard http components.

The design at the bottom has a REST character: many endpoints (resources), but the business protocol is executed by via a constrained set of messages (ie, the uniform interface) that have well specified semantics. By moving the protocol complexity from the messages to the resources, message exchange becomes business protocol agnostic -- you can achieve scale with standard components because they can participate in the exchange of representations without needing any specialization at all.

The one in the middle is Rails -- Jim Webber, 2011.

The notion of the uniform interface is critical in the success of the web; it's the constraint that allows clients (browsers, crawlers) and intermediaries (caches, reverse proxies) to develop independently of servers.

What features/constraints can be achieved with REST based API that cannot be with only HTTP based API

Fielding's thesis gives us this definition of the uniform interface:

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

Hypermedia is huge, but it's not HTTP -- in the web stack, hypermedia support comes from HTML. It's the highest level in Richardson's model; the technology that is most often misunderstood when implementing a web service.

As Fielding (2008) bluntly clarified, this architectural constraint is *not optional:

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.

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types.... From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.

Fundamentally, consuming a REST API is like browsing wikipedia

enter image description here

Specialization and innovation depend on an open set. Note the implication: the open set is potentially changing and boundless. Change is a very real thing -- for reference, see just about any discussion of API versioning. Coupling independently developed clients to an open set of resources is completely unreasonable.

But with hypertext, can use a closed set of resources (bookmarks) to provide representations to the client that direct them to today's open set of resources, and then change the bookmarked representations tomorrow when you innovate.

It's a lot of work though -- much easier in the short term to communicate the available resources to the client out of band (ie, API documentation) which allows you to use representations that don't specify hypermedia control elements (example: application/json).

REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them.

To give "long lived" a sense of scale -- httpd was first implemented over 25 years ago, and the cutting edge of HTTP is version 2. HTML is more volatile (and somewhat older); it is all the way up to version 5 (numbering somewhat confused by the fact that WHATWG considers HTML to be a living standard).

There are some API like Jersey JAX-RS which provide API implementation for REST based on HTTP. What extra features they add on HTTP basics?

Umm... not a lot?

That's not a particularly charitable answer, and Fielding was one of the expert members, so you are invited to take my skepticism with a grain of salt.

But here's what Marc Hadley had to say in 2008

I think the API encourages a resource-centric view and makes developers think about the identifiers of their resources and the methods they support. Declarative support for content negotiation works well and the default resource life-cycle encourages a stateless approach.

Suggestion, keep "think about the identifiers of their resources" in mind as you watch Stefan Tilkov's talk REST: I don't think it means what you think it does (slides).

Here's Marc Hadley on the weaknesses of the work

If I had to identify a weakness it would have to be limited support for hypermedia as the engine of state - whilst we provide good support for extracting information from request URIs and building URIs to resources, its still very much left to the developer to use hypermedia in representations appropriately.

Yes, generation and parsing of nicely designed URI has value. However, nicely designed identifiers are not among the REST architectural constraints. Hypermedia is.

In conclusion, if you are looking to understand the distinction between HTTP and REST, JAX-RS won't help.

Original Thread

By anonymous    2017-09-20

This simplified example shows a problem occurs when an object has id "summary". What is the best way to solve this? From a REST puritan perspective, what should be the solution?

As far as REST is concerned, the URI are opaque. Spelling is absolutely irrelevant. You could use URI like


and as far as REST is concerned, that's spot on. See Stefan Tilkov's talk REST: I Don't Think It Means What You Think It Does.

What you are asking about is URI design, how to adapt conventions/best practices to your particular setting.

One thing that will help is to recognize is that summary is a resource, in the REST/HTTP sense -- it is a document that can be represented as a byte sequence. All you need to do is figure out where that resource belongs (according to your local spelling conventions).

Continuing to borrow the "books" example used by others

# Here's the familiar "URI that identifies a member of the books collection"

# Here's the summary of the /books collection

Put the in query parameters. From what I understand this is against standards

Not as much as you might think. REST doesn't care. The URI spec expresses some views about hierarchical vs non hierarchical data. HTTP supports the notion of a redirect, where one resource can reference another.

GET /books?id=12345

302 Found
Location: /books/12345

You also have options for skipping a round trip, by returning the representation you want immediately, taking advantage of Content-Location

GET /books?summary

200 OK
Content-Location: /summaries/books


Original Thread

By anonymous    2017-10-15

According to this guide of designing REST API endpoints, we should never use action/verbs in URL

REST doesn't care what spellings you use for your identifiers. That's part of the point. /e25928c5-7b4e-44b8-be83-24ed9c9f8d3b is a perfect fine identifier.

Stefan Tilkov gave a really good talk on this.

Please guide me how should I proceed in such scenario.

Think about how you would do it with a website. You would be on a page somewhere, with a bunch of links, one of which had a label on it like changeTheme. You would click that link, and be presented with a new page that included a form, with a list of available themes. You would pick the theme you want from the list, and submit the form. That request would go off to the back end, updating some resource. As a side effect, the record of your theme would be changed. You would get back perhaps a message telling you that the change had been made, redirecting you back to where you started.

That's REST.

So the nouns you are looking for are the nouns in the integration domain that you are using to navigate the change theme protocol; in other words, they are the form, and the form submission inbox.

Jim Webber describes the model of the web as that of a 1950's office; you get work done by retrieving forms, filling them out, and dropping them into inboxes.

The mental mapping you want is not that of an action (that's too bold) but of a request -- you are sending a message asking somebody else to take the action you need. The actual action is the side effect. So the "form submission inbox" is the collection of pending "change theme" requests.

Use whatever the local spelling convention is for that sort of thing.

Stay away from the idea that the resources are representations of your domain; the resources support your integration protocols, and the names of the resources are drawn from the language of your integration domain, not the language of your business domain.

POST is almost always an acceptable choice for sending requests with unsafe semantics to the server. Remember, we're here because the web worked, starting from a media type that supported only GET and POST.

Original Thread

By anonymous    2017-11-13

Since there is no actual overlap between email addresses and IDs. I would just use same endpoint for both. Especially if GET /users/{id} is already a published interface.

So, I would go with 1st method.

GET /users/{identifier}

Then on the API server you have to add a small check, whether {identifier} is a number or not.

I would also like to note, that "pretty URLs" do not make it REST :) You probably will want to watch this lecture:

Original Thread

By anonymous    2017-11-27

I am getting an impression, that you are trying to turn your API in something like "SQL over HTTP". That's will obviously create something of clusterfuck, due to the amount of optional parameters.

You probably should read this article and watch this lecture on the given subject.

I personally prefer the endpoints to always return the same fields and use the parameters, when I need to expand one (or more) of those fields, or when the endpoint contains a collection and I want to filter/paginate the results.

That way the "parsing" of user's request becomes a lot simpler.

It also seem, that your "include" field provides a way for user to reach in the DAL and directly fiddle with persistence. You end up with layers leaking the abstraction.

Original Thread

By anonymous    2017-12-04

You should probably watch this lecture and read this article.

REST a such has nothing to do with how much of available HTTP methods you use. So, the quick answer is: yes, it could be considered "restful" (whatever that actually means).

Buuut ... it most likely - isn't. And it has nothing to do with the abuse of POST calls.

The main indicator for this magical "RESTfulness" has nothing really to do with how you make the HTTP request (methods and pretty URLs are pointless worthless as a determining factor).

What matters is the returned data and whether, by looking at this data, you can learn about other resources and actions, that are related the resource in any given endpoint. It's basically about the discover-ability.

Original Thread

By anonymous    2018-04-08

REST doesn't care what spellings you use for your resource identifiers. See REST: I Don't Think it Means What You Think it Does, by Stefan Tilkov (2014).

The key idea: in REST, the client follows links provided by the server, rather than constructing links described in documentation.

Original Thread

Submit Your Video

If you have some great dev videos to share, please fill out this form.