�ݺ�ߣ

Editor's Notes

• #4: Why should we care about what REST really is?“Once upon a time, in the age of fairies and leprechauns, an ice-cream maker named Roy Fielding discovered a seed that people have been using in a remote land, called cacao. Keen on using that discovery, he mixed those seeds with sugar, milk, eggs, cream and sugar and got the inhabitants of his village to try it.Everybody was excited about this new ice-cream. They all knew the ingredients of course, and some of them were using it, but the mixing of all of them in one ice-cream was somewhat a revelation for many. Villagers became very fond of that new ice-cream, and Roy decided to call it chocolate ice-cream. For a long time, many people in Roy’s village consumed chocolate ice-cream, and all was good in the world. That village was named Web and declared chocolate ice-cream it’s local speciality.One day, a traveller from the village of Soap, that everybody was calling mister Sainsbury, came to the village of Web and saw how much people liked that chocolate ice-cream. You see, in the Soap village, the local dish was made of soap, and people didn’t like soap very much. He decided to bring back the idea in his own village.Sainsbury tried to reproduce an ice-cream people would like, and put milk, eggs and sugar, but because he didn’t know about cacao, he decided to use vanilla POD instead. And he got his fellow villagers to try the ice-cream, and they all liked the ice-cream very much, all all was good in the world. And it was named chocolate ice-cream.Mister Sainsbury knew that the rest of the country was still eating soap, and decided, as a good business man he was, that they should all enjoy his chocolate ice-cream. And as mister Sainsbury got so rich from selling soap before, he started promoting his new chocolate ice-cream in the whole country, and soon all were excited about eating chocolate ice-cream made of vanilla.One day, an engineer from the village of Wikipedia came to Web and asked for the national desert, the chocolate ice-cream. The villagers happily provided him with a wonderful cocoa-based chocolate ice-cream. When the engineer started eating it, he started screaming:Engineer - This is not chocolate ice-cream! It’s not even the right colour! Do you think I’m a fool?Roy – This is chocolate ice-cream. It has cacao in it, as it always had.Engineer – No nono! Chocolate ice-cream is made of vanilla! Everybody knows that!Roy – No, it’s made of chocolate, if you put vanilla in it it’s vanilla ice-cream, because there’s no chocolate in it?Engineer – You’re just an extremist, you’re trying to confuse us!Roy – …And that’s when the villagers of Web decided that it was time for them to travel the country, and explain to people the advantages of putting cacao in their chocolate ice-creams.”
• #5: REST is a set of underlying architectural constraints of the Web – the largest informational system ever built, yet simple and scalable.Fielding’s dissertation is a scientific paper and thus is not particularly easy to understand and start learning REST.We start with the goals of the web architecture, that REST constraints are aimed to lead to.Further we evaluate common techniques, used by so called (and often self-proclaimed) RESTful services, against contributing to those goals.The goals are:
• #6: Web applications are designed to be loose coupled.The web could not ever be deployed as a monolith system.The web is an ever-growing ecosystem of loosely coupled servers, clients and intermediaries.Servers go down, go up or get updated – web still works.
• #7: The Web have traded feature-richness for simplicity and uniformity.More intermediaries can implement simple and uniform protocol (HTTP) in order to provide features to servers and clients.
• #8: Web caching at the proxy-level is an example of a high performance achieved due to the web’s uniform interface.Stateless nature of HTTP makes it ultimately scalable as well.
• #9: Some don’t like chocolate ice-cream.Not everyone needs loose coupling and scalability taken to such an extreme.Not everyone has to build HTTP-based systems RESTful.Do whatever your system needs most. Just don’t call it REST if it’s not.
• #10: Which URI is (more?) RESTful?Many developers start designing web APIs with URLs and ask on forums “how to design RESTful URLs?”This question is nonsense.The Web treats URL opaque.Some websites use so called “hackable” or “guessable” URLs for SEO purposes and to allow users overcome some usability issues.“Hackable” URLs have nothing to do with REST.
• #11: Is it REST?No SOAP, no WSDL, no XML namespaces. It should be REST, right?
• #12: Is this REST?We got JSON. JSON is RESTful, right?
• #13: No. Previous examples tunnel requests through a single URL, burying business logic in the request body.From the web’s perspective these are not at all better than a good old WS-* SOAP service.We are still on the lowest level of the Richardson REST Maturity Model.We need resources in order to get a higher rank.
• #14: Now we have an awesome resource. Is it REST now?
• #15: The previous example did what is called “URL tunneling” – it passes all data, required for the request, in the URL.
• #16: This one still uses URL tunneling, but it more accurately chooses the HTTP method.
• #17: All the HTTP methods impose particular properties on requests, done with them.Idempotent requests can be retried any number of times and the result should always be as if the request have been handled once and only once.Safe requests should have no side effects that the client can be held accountable for.
• #18: Now we nicely defined a user resource and we care about HTTP methods.We GET the user, change his settings and PUT the whole user back.The intent was only to change the user settings, why do I have to PUT the whole user?Some try to solve this problem by standardizing a new HTTPPATCH method, although Web has been living without it all the time.
• #19: Resources != Objects, HTTP Methods!=Business Operations.If you find yourself missing domain-specific HTTP methods, think about your resources again.A URI identifies only one resource, but a resource can have more than one URI.
• #20: Sometimes people find themselves limited to do CRUD (Create Read Update Delete) APIs because of the limited set of HTTP methods.
• #21: Best example of CRUD is Excel: domain logic is in the user’s head!We want domain logic to be on the server. User should just navigate his way through the workflow.
• #22: A better approach would be to model user settings as a resource on its own.
• #23: Sometimes APIs are documented using URL templates.This hinders loose coupling.Only URI templates shared out of band are bad. User can safely discover a template by GETting a resource (like Open Search does).
• #24: Now we have resources,their URIs and we appreciate HTTP methods.Still we have a long way to go to be RESTful according to the Richardson REST Maturity Model.
• #25: When putting the API’s version number into the URL, we couple our clients to that particular version.There is no way we can build a future-proof client for that service.
• #26: A much better way of dealing with versions is an HTTP Accept Header.It can incorporate a version number for our specific media type.
• #27: The same is with languages.The only valid reason for that is if different languages discriminate unique resources.
• #28: HTTP supports Accept-Language Header for that.
• #29: If we stick with HTTP features instead of inventing the wheel on top of it, we arrive at the next level of the RRMM.
• #30: What is wrong with this?
• #31: Generic media types.Clients are tightly coupled to our API’s documentation in order to figure out how to handle the data.Otherwise it’s just an arbitrary JSON BLOB.
• #32: Messages should be self-descriptive.
• #33: Given we know that the media type describes a product.But we have no idea, what we can further do with it.We are again bound to the documentation.
• #34: A better way is to supply next options for that resource in its representation.This is exactly what the web applications do with anchors all the time.We can also use something like an Xform and specify the HTTP method along with required data.
• #35: After enabling hypermedia controls in our resources representations we finally achieve the top level of the RRMM.Now our RESTful application looks almost the same as any conventional website: navigate between resources, transitioning the business workflow from state to state. Much like an online shopping process.And there is nothing wrong with it. Websites are in fact RESTful applications.So why do we treat our APIs differently, designing them separately from the UI, putting them on a separate URL?Just provide computer-friendly representations to the resources you human users are already working with through the UI.
• #36: Recap of the presentation.
• #39: Recap of recap of the presentation.
• #40: People seem to learn better when they see the big picture, so here is one…