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

This presentation was recorded at GOTO Amsterdam 2014. #gotocon #gotoams
gotoams.nl
Stefan Tilkov - SOA & REST Authority, innoQ Founder
ABSTRACT
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:
gotocon.com/am...
/ gotoamst
/ gotoconference
gotocon.com
#REST #HTTP #SoftwareArchitecture #designpatterns
Looking for a unique learning experience?
Attend the next GOTO conference near you! Get your ticket at gotopia.tech
Sign up for updates and specials at gotopia.tech/n...

[@a0um]

Very very good presentation. Impressive the level of engagement he managed to get from the audience.

[@DevOpsCraftsman]

As reference, you can take a look at js libs using HATOAS approach by consuming endpoints returning html instead of json: htmx unpoly hotwire (turbo) livewire (laravel)

[@okerror1451]

But at the same time, we should bend a knee and respect JSON for how wonderful it made the journey so far

[@nyrtzi]

Identify things with stable links, use data appropriate formats, traverse things through links and provide metadata on all of the former. I don't get the people saying that this is too vague or requires concrete examples. All of these things are present on any simple web page if you understand the technology well-enough to know what the terms mean.

[@joonhasebring]

Versioning in the URL IS a good thing if its a version of your contract, not about how its implemented. If you don't use a version, then having new data contracts will result in having to come up with different naming because you NEVER change your existing contracts, similar to how you approach in an Interface. Versioning can be a subdomain or a sub folder. I don't agree with this guy on that but he's pretty great otherwise.

[@setlonnert]

+Joonha Chu If I understand this correctly, what is at core stated in the lecture is the familiar difference between protocols and APIs. He mentions it at the start but could emphasized it more throughout. Differences in protocol versioning often doesn't obstruct each other, and can live side by side through the same "entry point", e.g. HTML and HTTP. The interesting thing is that developers doesn't at start get the benefits of protocols versus APIs. Even if the protocols often are serial, they often loosen up any language dependencies, or system dependencies, but also of versioning. They also can abstract the communication in ways APIs often do not. REST often is used in a way that leans towards APIs -- but isn't fully as it also rely on HTTP, a protocol, so it becomes a mixed approach.

[@kevinfleischer2049]

@Stefan Tilkov At 34:20 you talk about having "acepting/liberal APIs" and that this is a good thing. I work on an application that does that. And it is hell!. We got so much rubbish into the system that now the DB is full with trash (somebody had the great idea that constraints on the DB are to expensive too...) We came to the conclusion that you should enforce your interface to the clients. The sad thing was that the system had XML interfaces with XSD! But nobody would use the XSD to validate messages with. They simply send what they thought is correct. We build a new system for another business case and had been very strickt with the XSD validation. Everything invalid went back to the client with an XSD-Invalid Error. The quality of the data and the error possibilities inside the code are so much better.

[@user-sw1wq8lh2w]

+Kevin Fleischer what I thought he said was you can ignore the data, he says just don't reject the request based upon it containing malformed data

[@kevinfleischer2049]

This is not a solution. How does the communication partner know that his request is ignored or not? I believe liberal APIs/protocols are a thing for human communications. But IT systems should stick to the interface definition. That way, everybody can expect certain outcomes.

[@user-sw1wq8lh2w]

+Kevin Fleischer they k own which fields are accepted by the api, maybe return a notice of dropped fields?

[@deloftie3619]

It is not about ignoring the actual request. If the server cannot process the request it shouldn't just fail silently. It is about ignoring stuff in the request that the server doesn't care about. For example I want to update say the price of an apple on the server. I put the new price onto the server, but I send a whole lot of irrelevant meta-data. Instead of the server saying "I don't know what this meta data is" and then failing, the server says "I have no idea what this crap is, but you sent a valid price so I'm going to update the price"

[@JonasJurczok]

Being liberal in the API does not necessarily mean to "accept everything". IMHO it just means that you should only reject stuff that you cannot possibly transform into your standard domain object. At no point there should be garbage in your DB because of this. If you cannot transform it into whatever your database model dictates: throw an error. But be liberal there and try to accept as much as possible. At least this is how I interpreted this and so far it works.... :D

[@maazrehman8723]

This is a good talk , i think identification of resources is a bit misleading. A resource is a noun that categorizes some business functionalities in your applications like products , users etc

[@tux.solbakk]

About versioning, how would one go about if the API changes, like lets say you have an endpoint to fetch a person, that returns the persons name, called /person/{id}, now there is a need to split the name into first and last name, so the response need to change. The old response might not support this additional fields due to layout, or it might be that the old information is outdated, and no need for it to be in the response anymore. At the same time, there is clients that rely on it. It would also be nice to keep the same uri structure /person/{id} How would one do that without the versioning in a better way?

[@mazyvan]

Tux Solbakk totally agree

[@Kessra]

While Stefan mentioned that adding version information for pure data objects is okay'ish the actual identity of the person isn't changed by the internal model change. I'd avoid therefore to change the actual URI of the person by adding version information to it. How would a client be informed about the different versions of the resource? Ideally a client only sees one URI for the person and receives a representation it can handle. Such capabilities are usually agreed upon via content-type negotiation. A client supporting version 1 media type will receive the old representation format while clients supporting the new media type will receive the new representation format. This, however, is also not ideal to start with as you might have to define a completely new media type just for splitting up a name. Furthermore this media type is probably to specific for wide use and new clients might not be aware of different versions without consulting an out-of-band documentation. You could introduce media-type minting by adding parameter to the media-type like "application/vnd.person+json;version=2" or the like to indicate that your client is capable of handling v2 response formats of persons while in the absence of a version parameter a response for v1 would automatically be generated. This unfortunately only works for selected media-types that are usually proprietary and often not standardized. If a client now wants to retrieve a different, probably standardized representation there is no way for a client to hint a server about whether a v1 or v2 representation it wants to receive without relying on a pragmatic but non-ideal approach like including version numbers in the URI, as this semantically separates the same person into multiple distinct identities. The underlying issue here in general is, that a client already assumes that a resource has a specific type and thus expects certain fields to be present. In the absence of expected fields such clients will break. Typed resources therefore violate the REST architectural design philosophy. According to Postel's Law a client should be as tolerant to input but as strict to output as possible. I.e. a client using a HTML representation usually doesn't care about the respective elements in the document as it simply will render what is defined according to the semantics defined in the HTML spec. But it couldn't care less whether it renders v1 or v2 of the person resource. The architectural design of REST doesn't coop all that well with the object oriented design most programming language utilize IMO. While technically it isn't hard to parse arbitrary content and get the data into an OO application, mapping it to an object of certain type usually goes hand in hand with assuming that the data follows a certain object model and therefore the resource itself return data of that type. The static nature of classes that build the template for objects in OO programming languages is to rigid to handle dynamic changes done to the data easily. REST and HATEOAS are specifically designed to support evolution over time though if breaking changes are introduced, Fielding claims that it is probably best to expose the service at a totally new host address rather than carrying around version numbers within the URI and therefore make the version part of the API, that might also affect other resources that aren't affected by the change. Last but not least Fielding noted that: "Versioning is used in ways that are informative rather than contractual"

[@sdsappsandgames6262]

What if you put an optional attribute in the request params/body which would help you understand which version of the api they want? It can default to 1 so that your existing clients don't need to change. I'm not sure if this is ideal but it definitely takes away the pain of having to change the existing clients.

[@MrAzulay]

Such a good talk, BUT. I don’t fully understand his versioning arguments. Of course breaking changes should be done in a controlled manner and not too often (favoring additive approach). But at some point mistakes that have accumulated just need to be cleaned up. At that point, why not a version prefix in the URI? Or header (which I also don’t fully understand why it would be much better.)

[@damaddinm88]

I love it. Funny I was thinking all those endpoint are restful because it depends on the context where they in.

[@jasmeet17mast]

URL at 1:20 www.ics.uci.edu/~fielding/pubs/dissertation/top.htm usefule

[@navaneethagastya]

Excellent talk, sir! :)

[@yurymetphosis5766]

Is there a simple and concrete example?

[@Kessra]

You have browsers and HTML as the de-facto reference implementation, then you have a web-based mail archiver (called mod_mbox) as well as the version control system subversion that where designed and implemented according to the constraints outlined by the REST architecture (Further reading: static.googleusercontent.com/media/research.google.com/en//pubs/archive/46310.pdf) that however showed that the constraints defined by the REST architecture are not sufficient enough for larger projects. As such certain extension to REST, such as CREST, REST+P, REST+E, A+REST, R+REST, REST+D and finally ARRESTED, were proposed.

[@roytouw4374]

Does Postel's Law interfere with the design by contract idea where the goal of input is a small input domain?

[@mazyvan]

This guy says that versioning the API itself is a bad idea. Well It's about contracts. Of course you could add more resources to the API without changing the version. That is because it's not a breaking change. But what if I just want to change the name of one attribute. The resources haven't changed at all. But my contract does. So how can my clients consume my API safety if they are looking for the old name? This is not a data, documentation or format change. You could use the accept header if you don't want to change the url. There is no correct way to version the api, but it should definitely be done. The first GOTO video I dislike

[@Kessra]

What contract do you usually have while serfing a particular Web site? Is your browser expecting that a certain Web page is returning some details of a car in a certain structure unique to cars? No, not really. According to Fielding: "Versioning is used in ways that are informative rather than contractual." (www.infoq.com/articles/roy-fielding-on-versioning) The actual issue here is that your clients are already dependent on the API and what it returns. They expect certain elements to appear as certain attributes or fields within the response and thus consider a resource to have a certain typed, which violates the REST architectural principles. Media-types should define the possible (admissible) elements as well as the semantics of certain elements in a message of that type and how the message has to be processed. The complicated part here is definitely the mapping from a resource's state to a concrete representation format. Depending on the media type used this could involve a bunch of transformations, additions and cleanups. Proprietary and non standardized media types contain the risk that they either are not specified (enough), are to restrictive or that they are likely to change rapidly. In contrast the'd also allow for customization and stakeholder related behaviors such as flexible parameter support that'd allow to specify a version parameter or similar stuff that take an effect on processing a document of that kind. The contract between client and server is actually based on the agreed representation format and thus the content type exchanged. A client informs a server about his capabilities and a server returns a representation that is understood by the client. Though a media-type should not be something specific like a car-details message, as it probably would not see widely used by multiple clients, but be as generic as possible to be widely adoptable, i.e. something like a products description or something even more dynamic. That this does not map all to well to OO designs is not the problem of REST but the incapability of OO languages to adopt to changes in their class models on the fly. While it is technically possible to maintain the received data in generic data trees such as maps, collections or dictionaries (or whatever they are called in your OOP language of your choice), usually the data is mapped to concrete business objects assuming that the data already follows a certain domain model, which usually leads to failure if something unexpected appears in that data. The OOP vs. REST problems are similar to comparing SQL tables to MongoDB collections. The former one has a rigid (table) structure not allowing for adding or removing fields easily and supporting nested entries while the latter one shines on such features though might end up with more wasted space and maybe slower response times due to less efficient indices. Fielding mentioned that if you introduce a breaking change it might be better to deploy the new version of the service to a new host and consider both version as different applications. That way old clients still have the old server to talk to while new clients contact the new server.

[@yauhenibut-husaim5822]

​@@Kessra 1. Imagine Car model is given for you. You have the next properties: id, name, color; some time after if was decided to change name of property name to model; how program could self-adapt for that? it's possible only if: 1.1 -> you add property mapping as another resource; 1.2 -> you have some super smart AI that adapts for that with some chance; 2. REST specification is kind of "dream" of auto-generatable & self-adaptable client applications. Basically, when this guy shown an example with {"rel":"search" .... } and so on, there wasn't declared that the request should be a GET request. How the hell application guessed that it's GET? Why not POST? The same with his example about order status transitions. I suspect they are done using PUT or PATCH, but for client to be able to generate link or form an HTTP method should be provided in the response. The same with validation. What if query parameter accepts only integers from 1 to 10. It also should be expressed in the response and UI should be automatically adapted for that. Also what about more custom validation rules? Or imagine Car model having "imageUrl" property. How UI should understand, that "imageUrl" is an image and it should be displayed as image. We probably should put it into our receipt then somehow. Overall i think it might be possible to implement something like that with some special conventions and frameworks (that's what Google Forms are implemented) , but again - how to integrate it with UI/UX logic and design (try to really customize UI/UX of Google Forms without manual development). Imaging GitHub API (which is completely RESTful) will be displayed as such faceless HTML page from his example. It would be very hard to navigate through 100+ actions. In reality it's easier to just integrate client & server manually than support such flexibility. Giving such detailed "receipts" in API response it's almost the same effort than just implement full-featured client app :) Auto-generated UI might be an "option" for some cases (as in Google Forms), but for 99.9% of cases it's overkill. Basically, the more i'm trying to understand REST & RESTful - the more i understand, that nobody understand anything and just provide their interpretations. The API specification is not for machines, it's for developers. So it basically should be clear for developers, how to integrate with your service.

[@malleshk2091]

Nice talk. How is session management done in Restful service? If session key is stored and sent from client, then without storing session key in server side how can validation be done by server?

[@logiciananimal]

TBL's original proposal for the web had "expiring links". I wonder if some of these ideas could work to implement those.

[@spyderwon2573]

Curious about the statement at 26:30 discussing customers + orders + the hierarchy implied by the url. From how it reads, you'd call that url to get a list of all orders for a given customer. He suggests that that simply should return a link to where you can get the orders for a client? I've been going back and forth on that very topic the last few days. Following his line of thinking, what would be a sample flow for this? Any input is appreciated!

[@linkVIII]

json home still in draft

[@JohnSmith-he5xg]

Way too much "philosophy" for my taste. The talk could have been 10 minutes with no content lost.

[@IanMihura]

47:50 HTMX MENTIONED

[@damaddinm88]

Mhhh versionig is important for APIs. Bringing out the perfect api at first place is unlikely.

[@apiadept]

My favourite part of this talk kzbin.info/www/bejne/pqTTqmR-a6ZmfK8

[@stms999]

waaaay to philosophical. Or is it because I know nothing about the web ?

[@pedersenlasse]

No, it's because REST is not a concept that has much value outside academic circles. It describes the design principles behind the World Wide Web as a distributed application, not the API you built that happens to use HTTP as a transport layer. The majority of so-called "REST APIs" are not RESTful at all.

[@ILykToDoDuhDrifting]

this is dumb. this guy just likes listening to himself talk. of course you version your apis. even roy fielding says you can do it by using e.g. a different hostname. people's problems is not compliance with REST. customers don't care about REST. the problem is solving the problem suitably. complete waste of 40 minutes.