17 ms·

REST was never about CRUD

323 points by elkinthewoods 8y ago

LeonidBugaev 8y ago
Agree. The whole point of rules is that you allowed to break them from time to time. During development with Rails I struggled a lot, because it was forcing CRUD ideology in places where the custom route could work (and adding it was so painful). Standardization is fine, but usually it does not solve development issue, it solves management issue, which is common for big orgs not small ones. Especially when it gets on hype or forced by the top management, like it happened numerous times, with latest examples of React, GraphQL or Microservices.
- jively 8y ago
  True, in general any framework that claims to help build REST APIs can put you in a situation where it forces assumptions on you. Then the interpretation becomes the pattern, and it becomes a self-perpetuating fallacy.
- wukerplank 8y ago
  Hm, I never found adding custom routes to Rails painful - could you elaborate? Anyway, for smaller use cases I found Sinatra + ActiveRecord a great match.
  - LeonidBugaev 8y ago
    I'll be frank, the latest Rails version I used was Rails 3, and it was like 6 years ago, so I can't really remember details, except that I had to spread logic to like 3 files to make it work. Maybe things changed.
    - yxhuvud 8y ago
      No, you didn't have to spread out the logic like that in Rails3. You could do something like class AsController < ApplicationController def index end class BsController < ApplicationController def create end end end with routes like resources :as do resources :bs, controller: "as/bs", only: :create end
      - ryanbrunner 8y ago
        Even that is resourceful routing, just with nested resources. Doing a flat out custom route is even easier: class AsController < ApplicationController def custom end end routes: resources :as do member { get :custom } end
        yxhuvud 8y ago
        Yes, of course. The whole point of my example was that it is possible to do resourceful routing in a single file without having to resort to using custom routes. I try to avoid custom routes whenever possible - in my experience they lead to pain in the long run, more often than not.
  - rajangdavis 8y ago
    Sinatra is awesome! Had a project recently where Active Record and Postgres with Sinatra made sense and it was completely painless. Rails _might_ have helped, but I have come to enjoy Sinatra's flexibility. Been debating about making something in between, but working on other things.
- sureaboutthis 8y ago
  Standardization is in place for interoperability issues, not management. Rules are NOT made to be broken, as you claim, and I see more people getting themselves into trouble for thinking that. This is computer science, not a game.
  - coldtea 8y ago
    No, it's absolutely not "computer science". In fact the rules you talk of are totally ad hoc and/or cargo cult. At best, they're self-reported empirical (pre-scientific) findings. There's no systematic research that they're better than some alternative set of rules etc. People just adopt this or that framework or methodology (like REST) because some famous programmer wrote it or suggested it, some company promoted it, it picked up steam of GitHub and blogs, and so on. That's not only not "computer science", it's not even "software engineering".
- mschaef 8y ago
  > During development with Rails I struggled a lot, because it was forcing CRUD ideology ... This reminds me a bit of my first experiences with Common Lisp to write anything resembling serious code. (A Java compiler for my compilers class in school.) My education to that point had almost entirely been driven from a purely list based and functional view of the language. Instructors would default to lists at the expense of other data structures and strongly encourage 'non-destructive' operations at the expense of mutation. (Even the term 'destructive' carries with it an obvious negative and somewhat dangerous connotation.) Flash forward a couple semesters, and I'm trying to take this approach beyond writing simple unifiers and minimax search and apply it to a compiler with multiple layers of code that's being built up in phases over months. A month or so in, my resolve cracked, I started exploring some of the other options provided by the language (hash tables, vectors, mutation, etc.) and made a bunch more progress (and got something working by the end of the class). My point in saying this isn't really to advocate for mutation, etc., but rather to agree with your point that sometimes it's worth breaking out of self-imposed constraints so that you can face the external constraints that are probably more important. (ie: my business client probably doesn't give a damn if my RESTful interface is RMM level 2 or three as long as it lets her effectively run her business.) (One thing I'll add about the Lisp experience above is that it was more than half a lifetime ago... I'd probably be more nuanced with my use of mutation, etc. now than I was then. But then, I was much less experienced and a refugee from Pascal, etc. One of my constraints was my instructors' encouragements to avoid mutation... but another of my constraints was my own lack of techniques for working that way.)
chronicler 8y ago
I don't think anyone ever says RESTful services must be CRUD based, what they say is non-crud operations are hard to model in a RESTful service.
pas 8y ago
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 reified and URI-fied in the JSON.) > The workflow our API supports is more explicit, [...] Sure, that's pragmatic, but after much gnashing of teeth and scratching of heads, REST is about presenting options to the client by offering various media types (content-types), and letting the client request the best representation, and not really about a fixed ACL neither about fixed flow. From [1] again: "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]" [0] https://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post https://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post [1] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
- dnomad 8y ago
filleokus 8y ago
After using GraphQL for over a year now I rarely miss the good old REST days. Certainly the declaration of schemas/models in the beginning is maybe more cumbersome compared to REST. But when that is in place is just so easy to work with, no more adding extra field in responses to avoid doing multiple unnecessary queries, just lovely. When mutating state with GraphQL the suggested approach seems to be to have "action based" endpoints, i.e "publishArticle", which resonates well with me.
- jively 8y ago
  My biggest issue with GraphQL is the fact that what essentially used to be a database operation has now become a (coordinated) batch API query. So the operation has been split into microservices, then re-joined using a GraphQL interpretation SPoF, all so that client business logic can be encapsulated as a query string, instead of securing that effort as a specialised API endpoint. Moving flexibility to the client comes with all the inherent risk of that flexibility being available to (in a browser sense) a risky client. RPC over REST is a solved problem IMO, arguments about REST RPC semantics become ideological after a while.
  - rusk 8y ago
    > RPC over REST is a solved problem I'm interested in understanding more about this statement. Do you mean that all REST RPC libraries are sufficiently developed such that you don't really need to worry about RPC being tricky, or that we all just as a community understand the best strategies and common pitfalls. Or do you mean a specific technology? Just wondering cause whenever I hear the term RPC as an experience developer I just shudder (-: Thanks!
    - jively 8y ago
      I meant that there are well discussed strategies for handling calls that are RPC-oriented rather than CRUD, not that there are REST libraries that have solved the problem. Ultimately we find ourselves building 80-90% CRUD operations with edge cases that don’t entirely fit with the straightforward RESTful toolset, and in those situations making a call on how to handle it in code is a topic that has by now been more or less discussed to death and becomes a stylistic choice. REST isn’t a protocol, there is definitely interpretation at work. I was using the term “RPC” to cover topics that are outside the scope of CRUD, “do a thing” as opposed to “manipulate a thing”.
IshKebab 8y ago
REST is kind of a worthless term at this point because really nobody agrees on what it means. I'm sure somebody will reply saying "no it clearly means this!" or "it obviously means using HTTP how it was supposed to be used" or "those other people just don't understand REST", but the fact is we still have articles - in 2018! - that are trying to explain exactly what "REST" is.
- LoSboccacc 8y ago
  just because people don't understand doesn't mean everyone is wrong/right https://i.imgur.com/MCsxsAY.jpg https://i.imgur.com/MCsxsAY.jpg
  - IshKebab 8y ago
    It means using the term "REST" for communication is useless - exactly like in that cartoon you linked.
- jimjag 8y ago
  If people don't agree with what it means, it's because they aren't spending time reading the actual dissertation. Instead they are kind of glancing over it and depending on others interpretations to create their own. As someone who writes protocol specs, Roy takes great care in being as clear as possible: confusion, inconsistency and misinterpretation are not Worthy Things in protocol implementations. To truly understand REST, you MUST understand HTTP and the rationale behind it.
  - oftenwrong 8y ago
    Perhaps he should have written a specification for REST.
  - dwaltrip 8y ago
    Words are defined by their usage, not by what one person thinks, even if they came up with the word.
fanf2 8y ago
The draft BCP56 revision, on the use of HTTP as a substrate, is a nice primer on REST API design https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis
nostalgeek 8y ago
It seems to me that REST "was never meant to solve web developers problems" at first place and that dissertation wasn't addressed to them. I'm glad we are getting out of REST. Devs need protocols and specifications, not vague architectural ideas that leads to "you're doing it wrong" blog posts. There is no "you're doing it wrong" with GraphQL, or SOAP, or JSON-RPC, you either follow the spec or you don't.
- noir_lord 8y ago
  I just use this https://labs.omniti.com/labs/jsend https://labs.omniti.com/labs/jsend and typed it up via TS. It makes for nice code. Promise<JSendApiResponse> With the benefit of HTTP level stuff not been mapped onto application level stuff. I like KISS with this kind of thing and if you need a more complex solution it handles that as a starting point.
  - indexerror 8y ago
    You can do this with Axios too: interface IResponse { foo: string } async function doSomething() { const reponse: AxiosResponse<IResponse> = await Api.call() ... // or you can use AxiosPromise<IResponse> without the await }
- organsnyder 8y ago
  OpenAPI (née Swagger) helps a lot with this. While I'm sure that many purists would argue that you're not really doing REST if you have an OpenAPI contract, it certainly helps a lot with making APIs more usable to consumers.
- bborud 8y ago
  > Devs need protocols and specifications, not vague > architectural ideas that leads to "you're doing it wrong" > blog posts. This is precisely it. If an integration mechanism can't be implemented as a clear and uncomplicated library that strongly encourages correct use by making it the path of least resistance, it probably isn't any good. (And note that I said "library" rather than "framework". This is important as libraries are more like a thin layer of glue while framework is more like a metastasising cancer) Most of the time, REST, strictly speaking, demands too much attention even for relatively simple stuff, and therefore is not a good integration technology. However, some adaptations of REST are. The one thing that is a bit sad is that there is some nomenclature confusion. These days a REST API doesn't refer to Fielding's vision, but a more practical adaptation of the mechanical bits of it.
hirstys 8y ago
Hmmm, but is REST so often conflated with 'just' CRUD, because that is all people really want from REST, or is it that this perception is so pervasive that people don't know what the potential is. Chicken or Egg? I'm saying Egg, but I'm not saying which that relates to :)
- clan 8y ago
  CRUD is easy to understand and close to the core of tasks that programmers at large need to do. Thinking in terms of REST requires that you concern yourself about the full infrastructure. Many programmers i have met simply do not care. Super nice properties such as cacheable and discoverable are outside their domain. Most simply just want remote RPC. Try convincing a programmer of the benefits of HATEOAS is though. It will be dismissed as too much hassle with no real benefit. But if you look at it from a data architectural perspective everything just "clicks". Few projects are however approached from that angle.
  - tjpnz 8y ago
    HATEOS can be a weighty concept to get across and it never clicked for me until I read a book on it. I still think there are aspects of it that could be learned easily enough in isolation though. Understanding media types for example allows you to develop some really nice schemes for API versioning. But few people are even willing to learn that and just butcher their URLs instead.
lmm 8y ago
The useful/valuable part of what came to be called "REST" (very little of which is found in the dissertation, it's an accident of terminology which has lead a lot of people astray) is all about CRUD, because CRUD is the only thing that makes sense to do with a generic "resource".
- icebraining 8y ago
  POST is used for way, way, way more than any CRUD operation.
  - lmm 8y ago
    Indeed it is, but at that point it's not "REST".
    - icebraining 8y ago
      Why wouldn't it be?
      - lmm 8y ago
        The HTTP verb isn't reflecting what's happening, and likely some important considerations aren't being represented as entities.
        icebraining 8y ago
        The description of the POST method is very generic; one of its functions detailed in the HTTP spec is: - Providing a block of data, such as the result of submitting a form, to a data-handling process; Which fits with much more than mere CRUD. And it's specifically written that it doesn't have to result in the creation of a new URI-addressable resource. (Also, REST isn't HTTP, you can comply with the former even if you're violating the latter, and vice-versa)
        lmm 8y ago
coldtea 8y ago
REST was never that good to begin with. (Not even as originally intended, which is very different from RESTful way 99% use it -- originally REST was all about self-reporting and discoverability, which is not used, and irrelevant to most use cases). Having JSON as the response, and a scheme to address entities, was good. Even using HTTP action semantics was OK (though debatable). But that's far from what REST is about. Something like JSON-RPC would be a much better for web API needs.
- sureaboutthis 8y ago
  That people misused REST is not what made REST "never that good" (in your opinion). In fact, it was this misuse that frustrated Dr. Fielding more than anything else.
  - masklinn 8y ago
    > That people misused REST is not what made REST "never that good" (in your opinion). I used to be partial to that interpretation, but after a few years of looking at it, at what people do and at what's actually valuable, I've come to the conclusion that coldtea is correct: REST as originally intended was not that good for programmatic contexts. It certainly didn't help that it got quickly buzzwordified as "actually use HTTP properly instead of just shoving your garbage through POST all the time" (the original sin of SOAP or XML-RPC), but even then what makes "REST" work for browsers (which is what the concept was extracted from) is that there is an intelligent agent doing the discovery and driving the interaction. That's not useful for a programmatic API. You can add a discovery layer to a programmatic API (as e.g. graphql schemas & explorer tools) but requiring programmatic clients to go through such a discovery layer just makes interacting with the API painful for no value. Traversing a few pages when clicking around in your browser makes sense, doing so from a programmatic client when you could literally just store the correct endpoint and perform your call directly is nonsense: it's inefficient, it's annoying and it's pointlessly verbose. Yet that is essentially what proper rest as described and clarified[0] by Fielding require. Even the "multiple interpretations" (multiple content types) option is worthless when browsers don't provide the flexibility required to do content negotiation[1] or leverage HTTP verbs beyond GET and POST. [0] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... [1] even in places where they allow actual mimetypes it's as likely as not they'll ignore it e.g. object/@type is a mimetype but no browser I know cares about it, most of them send Accept: ∗/∗ and firefox sends its pagewise/default Accept.
sureaboutthis 8y ago
Many years ago, Dr. Fielding would visit a forum or two and offer answers to questions about REST. I had a number of my questions answered directly by him which helped me through the years to discover how many people have no clue about what REST is and how to use it but wave the REST flag as if they did--and they don't. I believe Roy quit visiting forums for those reasons; a frustration dealing with all that.
- coldtea 8y ago
  Words are not defined by their creators, they are defined by their usage. Those people indeed know what REST is -- in fact, they define what REST is. When we talk about REST, we talk about how people use it. They might not know what "REST as defined by Dr. Fielding is" but that's not really relevant to them or to the industry at large.
  - nacnud 8y ago
    "use", not "usage". </joke>
    - coldtea 8y ago
      Not according to my dictionary: use: the action of using something or the state of being used for a purpose. usage: the action of using something or the fact of being used: a survey of water usage
      - itscaleb 8y ago
        Words are not defined by their creators, they are defined by their use. Those people indeed know what USAGE is -- in fact, they define what USAGE is. When we talk about USAGE, we talk about how people use it. They might not know what "USAGE as defined by coldtea is" but that's not really relevant to them or to the population at large. :-)
- frederickf 8y ago
  I'd love to read some of his original comments. Do you remember any of the threads? Are those forums publicly available?
billpg 8y ago
The way I think of it is that GET, PUT, PATCH and DELETE all deal with data, whereas POST is a call to action. It is a little unfortunate that we don't have a CREATE verb (distinct from the update-ness of PUT) and we need to use POST for this purpose.
- 0x445442 8y ago
  That's interesting. Are you saying that you view Posts as verbs/processes which only result in side effects of the underlying system but do not change the state of data? I'm trying to understand what you would consider the domain of actions that would fall under your Post categorization. Batch Jobs, Emailing reports etc.?
  - billpg 8y ago
    That's basically right. I view GET/PUT/PATCH/DELETE/CREATE as simple wrappers around SQL commands, with validation and authorization checks. POST is a call to do something with that data, which might include changing the data. Off the top of my head, logging in, actions with external systems, sending emails.
- ams6110 8y ago
  I've had to support http clients that could only do GET and POST. So I tend to do everything by those two verbs, even though it's not academically correct.
the_new_guy_29 8y ago
Only one thing about this article i have to say is that its posted on TERRIBLY designed page... Half of the screen black, align to the right and no "reading view".
- hirstys 8y ago
  Harsh but fair!? We're listening, feedback has been passed to the team who look after https://tyk.io/ https://tyk.io/.
lazulicurio 8y ago
I know it's not technically correct, but the conceptual definition I've found useful for myself is that REST is about operating on the HTTP layer instead of building your own layers on top of it. Why create your own custom error protocol when you can use HTTP error codes? Why develop your own caching strategy when you can use HTTP caching? Why create your own authentication mechanism when you can use HTTP authentication over TLS (or client certificates, or etc.)? When the article talks about how REST should be layered, cacheable, and client-agnostic, that's really the core of it to me. By thinking this way, you can see how REST helps you re-use already-existing infrastructure---proxies, load balancers, caches, etc.---instead of spending time and effort making custom solutions. It also helps provide guidance as to when REST may not be appropriate: can you answer those "why not HTTP?" questions? I've also found focusing on the resource/noun aspect (beyond considering caching) to be a bit of a "nerd trap"; it's possible to spend a lot of time chasing the perfect, "correct", solution. As the article notes, there's nothing wrong with "verby" URLs as long as you are using HTTP instead of doing your own thing.
- osrec 8y ago
  While I agree that we should not reinvent the wheel, caching data is often tricky with REST. In my experience, the caching aspect of HTTP can introduce unexpected behaviour into applications. To get round this, I see a lot of devs use POST requests for everything, and implement their own custom caching layer. Basically, I think HTTP caching is fine for files, but once you start working with complex data, things get cumbersome rather quickly.
  - cxmnvcxkldn 8y ago
    What the actual problem with caching is, is personalisation. This has nothig to do with REST.
  - organsnyder 8y ago
    For caching to work, you need to sit down—ideally with business stakeholders—and decide what the caching policy should be for each data element. For instance, in a healthcare domain, your core patient demographics—name, DOB, ethnicity, gender...—can likely have a fairly long TTL (perhaps even a day or more), since those attributes don't tend to change very often. However, something like a patient's list of upcoming appointments should have a very short TTL, since it changes more frequently. Once you've made those decisions from a business perspective, you can have your services send the HTTP headers to effect that caching behavior.
jstimpfle 8y ago
An idea that I've never heard expressed explicitly is how REST is basically distributed OOP. Both REST and OOP lead people to waste their time on unimportant questions.
beders 8y ago
The comments here show that there's still much confusion about REST being an architectural STYLE, not an actual architecture. If you can present your domain as addressable representations of resources and if you can lay out your business logic as changes to these resources, then you could use REST via HTTP to provide access to your service. Furthermore, if it is important to allow any client to connect to your service and you don't have any control over the clients used, then adopting HATEOAS provides a backward-compatible, future-proof way for client software to work with your service. If, OTOH, you have full control over the client-side, you can trade-off these abilities for a simpler model (like GraphQL, if you must, or simple RPC over HTTP) Know what you design for. Re Caching: Caching in HTTP is very flexible. E-Tags basically give you fine-grained control over how to cache and allow for significant bandwidth/performance improvement. However, in many cases your app will also benefit from an additional cache layer in your persistence layer. Don't confuse them.
mratzloff 8y ago
The main problem with REST is Roy Fielding's communication style. Here's a quote from a 2008 blog post: Apparently, I use words with too many syllables when comparing design trade-offs for network-based applications. I use too many general concepts, like hypertext, to describe REST instead of sticking to a concrete example, like HTML. I am supposed to tell them what they need to do, not how to think of the problem space. A few people even complained that my dissertation is too hard to read. Imagine that! Yeah, Roy. It's called being an effective communicator. Effective communicators include stories and concrete examples to help bring the audience along with them, instead of lengthy discussions of abstract concepts. Readers shouldn't have to perform exegesis on your slideshow and blog to get even a vague understanding of what you're trying to get at. To be clear, any difficulty with REST in practice is a direct result of an underspecified concept without a clearly defined RFC as it relates to HTTP. Fielding didn't define anything about REST in terms of HTTP. All of REST, as it relates to HTTP, has been an application of what other people think he meant. Nowhere in Fielding's 2002 academic paper[0], his 2008 talk at ApacheCon[1], or his blog[2] does Fielding have clear examples or thoughts on the kinds of specific details that Web developers often struggle with. Fielding, in my estimation, seems principally concerned with three things with regard to REST: 1) Every important resource has its own URI. 2) All interactions against that URI should be stateless and cacheable: all application state that is specific to the user should live on the client (e.g., local storage for browsers), and all shared state should live on the server. 3) Interaction with that URI should be the same regardless of client (browser, mobile app, etc.). Everything else is left as an exercise for the reader. [0] https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm [1] https://www.slideshare.net/royfielding/a-little-rest-and-relaxation https://www.slideshare.net/royfielding/a-little-rest-and-rel... [2] https://roy.gbiv.com/untangled/category/web-architecture https://roy.gbiv.com/untangled/category/web-architecture
- MaxBarraclough 8y ago
  > Readers shouldn't have to perform exegesis on your slideshow and blog to get even a vague understanding of what you're trying to get at. (Ironically?) I've found this same problem to be one of the best reasons to avoid WSDL/SOAP. Too much pie-in-the-sky waffle, not enough pragmatic real-life flavour.
ankurdhama 8y ago
The same old story with anything called "architecture patterns", you can look at them from different angles and each time you will have a new interpretation.
jillesvangurp 8y ago
Until AJAX happened around 2005, GET and POST were the only verbs you could actually use in a browser. Before then, REST was not a really a thing. It used to be that semantics of HTTP verbs had meaning in the context of e.g. caching and other middleware. But now that everybody uses TLS, having caching proxies acting as middlemen and interpreting http messages is not that common any more. REST was a nice idea when it got (re)invented about ten years after Fielding's thesis but it left too much open for debate, ambiguity, and nitpicking and quickly degenerated in different opinionated camps trying to retrofit new ideas to the existing practices around http, which mainly boiled down to interesting ways to do RPC. Before HTTP, people were already long doing RPC using e.g. DCOM, CORBA,RMI, etc. Reinveinting RPC over X has been the fate of pretty much every way we've come up with to make two computers talk to each other.
- naasking 8y ago
  > Before then, REST was not a really a thing. You only need GET and POST for REST. > Reinveinting RPC over X has been the fate of pretty much every way we've come up with to make two computers talk to each other. REST isn't just RPC, it's RPC with specific constraints to enable caching, scaling, adaptability, and distribution properties that unrestricted RPC alone cannot achieve. That's why REST is still important today, because RPC is too flexible, and RPC without constraints will inevitably run head first into all of the issues that REST solves for you. Unrestricted RPC libraries then let you "solve" these problems in myriad incompatible ways each with their own problems.
  - habitue 8y ago
    > Unrestricted RPC libraries then let you "solve" these problems in myriad incompatible ways each with their own problems. I mean, this is exactly the state of REST today. It's not specified well enough to admit general purpose clients (like, for example, GraphQL does) because it's just a "pattern" not a specification. Because every API has its own way of doing paging, subresource expansion, expressing side-effectful operations, etc it means every API has a corresponding custom-built client. > Caching Do these custom clients implement http caching? Not usually. > Scaling Arguably, REST is responsible for bringing about the rise of stateless API servers. We should be grateful for the good idea, and not feel compelled to adhere to the other aspects of REST if they don't suit our purposes. > adaptability Claims of additional adaptability in REST are usually talking about HATEOAS where each resource defines how it can be interacted with by providing links and semantic metadata etc. I will flat out say it: this doesn't work. Short of building some intelligent agent into your API client, hypertext will never be the engine of application state in any meaningful way. You can't just change the links and have the client magically discover the right thing. Fielding's thesis was talking about the web, where humans are the ones deciding which links to follow. It's a useless concept in API design, and it adds tremendous overhead for zero benefit.
guhcampos 8y ago
I don't agree with the article (to me REST started about CRUD, and obviously got overloaded with time), but that's not what I need to comment. That font in the titles could have been gorgeous, but that upper case "D" is offendingly bad.
- hirstys 8y ago
  Ouch! Take your point, but don't you think the feels you get from the lower case "about" in the title makes up for any failing in the "D"?
OldSchoolJohnny 8y ago
Half the page is a calendar widget?! This is the worst layout I've seen in a long time.
- hirstys 8y ago
  Harsh criticism Johnny! But we'll take it on board, feedback has been passed to the https://tyk.io/ https://tyk.io/ team, there is certainly an opportunity to adjust proportions here. As a matter of interest, which blog/article page layout do you really rate?
  - OldSchoolJohnny 8y ago
    I think I was that emphatic because I couldn't believe anyone would want to exhibit such an obviously flawed design in public until it was fixed. I'm still confused how this would make the light of day, but I guess esthetics and usability are something learned perhaps over time?
niftich 8y ago
REST as seen in HTTP has always been about resources (identified by URLs), representations thereof that take the form of a particular mediatype (selected explicitly or by content negotiation), and hyperlinks (with targets and rels). When resources are obvious nouns already present in the backend's data model, this maps well to CRUD. The problem comes when trying to describe complex mutations, because to most people, this feels wrong, instilled by years of Dos and Don'ts of half-baked lessons about Object Oriented design. In all this time between when Roy's thesis was rediscovered to promote an architectural style and when the trendiness of REST has finally run its course, there were far too many posts complaining about deployments missing hyperlinks (when usually, the API was externally documented, URLs templated, and its clients hardcoded, making many usecases of embedded hyperlinks moot), and not enough to reassure flummoxed designers that naming resources after verbal nouns or deverbal nouns is perfectly fine. Oops.
mi100hael 8y ago
I disagree with the article and the examples provided. The author has left out a few key components of REST in their initial distillation. Critically: > REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. So given the example from the article: POST /articles/{articleId}/approve This URL does not point to a resource, and the HTTP verb does not describe what action is being taken upon a resource. It's also not using the representation of a resource to capture intent. It's also worth noting that a GET for the article would return the "status" field and presumably other PUT requests to update the article would either act directly on the article or have other vanity action URLs, making the API more verbose than if everything were done properly. A RESTful design would be in essence CRUD. It would have a url (/articles/{articleId}) identifying a resource, it would have a representation of a resource that includes a "status" field, and changing the status of the article would involve a PUT request to the URL of the article with the desired change of state.
- macca321 8y ago
  It's a "request to approve an article" resource, even if it hasn't explicitly been modelled that way.
  - mi100hael 8y ago
    By that logic, SOAP is RESTful.
- draw_down 8y ago
  Oh my god just freakin kill me already. You can never do this shit right, it’s extremely tedious.
lloeki 8y ago
The author proposes: POST /articles/{articleId}/submit POST /articles/{articleId}/approve POST /articles/{articleId}/decline POST /articles/{articleId}/publish I find this troublesome because the URL path component then includes a verb, an action, so there are two verbs in the same sentence! This can be adjusted to: POST /articles/{articleId}/submitted POST /articles/{articleId}/approved POST /articles/{articleId}/declined POST /articles/{articleId}/published Now the URLs really represent resources on which HTTP verbs operate, and you can readily guess what GET (if needed/applicable) on each resource would give you. There is some cognitive dissonance introduced by the inconsistency of abstraction levels between the former "RPC style" (where HTTP verbs are mere actuators† and the intent is in the URL and/or in the payload), and the latter "REST style" (where verbs carry intent acted upon resources). EDIT: I do not advocate for one over the other, merely that an API should be consistent overall and not mix both. † They are used as pure HTTP feature control (like caching) and do not carry application-level semantics.
rhacker 8y ago
I've been a long time fan of what this article is saying - but I didn't know it was a thing. Now if I ever run into CRUDdy teams, I have something to share with them :)
zzbzq 8y ago
Despite the architectural principals, it's named REST--REpresentational State Transfer. It's really hard to twist and contrive a situation in which "REpresentational State" is not CRUD. It can be done, but it's awkward. As soon as you're doing non-CRUD operations, it's really hard to model them as representations of state, and it's sometimes very unpleasant to use APIs where the designers tried too hard to make the peg fit.
coding123 8y ago
My main gripe with REST is that it's totally not future proof. The notion of RPC has been around forever. REST has basically completely replaced that. Http status codes and REST URLs are not future proof. We have already seen superior connection types (web sockets) come (and then basically go) that don't support the notion of URLs and (well they do for a second, but after that the original connection the URL is meaningless for the traffic flow). With Http2 we're seeing the return of lightweight connections (basically similar to websockets but have more graceful re-connection options). But http2 feels like a patch to me. I don't really want to bind the future of Apps to a bunch of URLs. I'd rather tie my app to a client that has a rich semantic set of objects and methods that pull down data, can update data, etc... When we use REST as our layer to convey the API itself, we really lock ourselves down to a very specific set of URLs and HTTP Status codes. I'd rather have a rich error object thrown, not an HTTP status code that I have to examine. I've had a pretty strong disdain for REST for the last few years and have been actively finding replacements. The closest I can come up with is Grpc. I'm dying waiting for Google to finish up Grpc-web however. If we continue to tie ourselves to a bunch of server resources by URL we're going to take forever to get off this archaic system that has no long term future.
- ako 8y ago
  Do you think the web could have been built with RPC instead, and be just as successful?
didibus 8y ago
I'd like to implement such and API, but I feel often time its not that we don't want to design an API that way, but that we fail to successfully implement one. I'd like to hear about guidelines, like for that transaction workflow example, how would you implement this? What would be your data model?

323 points by elkinthewoods 8y ago

Agree. The whole point of rules is that you allowed to break them from time to time. During development with Rails I struggled a lot, because it was forcing CRUD ideology in places where the custom route could work (and adding it was so painful). Standardization is fine, but usually it does not solve development issue, it solves management issue, which is common for big orgs not small ones. Especially when it gets on hype or forced by the top management, like it happened numerous times, with latest examples of React, GraphQL or Microservices.

jively 8y ago
True, in general any framework that claims to help build REST APIs can put you in a situation where it forces assumptions on you. Then the interpretation becomes the pattern, and it becomes a self-perpetuating fallacy.
wukerplank 8y ago
Hm, I never found adding custom routes to Rails painful - could you elaborate? Anyway, for smaller use cases I found Sinatra + ActiveRecord a great match.
- LeonidBugaev 8y ago
  I'll be frank, the latest Rails version I used was Rails 3, and it was like 6 years ago, so I can't really remember details, except that I had to spread logic to like 3 files to make it work. Maybe things changed.
  - yxhuvud 8y ago
    No, you didn't have to spread out the logic like that in Rails3. You could do something like class AsController < ApplicationController def index end class BsController < ApplicationController def create end end end with routes like resources :as do resources :bs, controller: "as/bs", only: :create end
    - ryanbrunner 8y ago
      Even that is resourceful routing, just with nested resources. Doing a flat out custom route is even easier: class AsController < ApplicationController def custom end end routes: resources :as do member { get :custom } end
      - yxhuvud 8y ago
        Yes, of course. The whole point of my example was that it is possible to do resourceful routing in a single file without having to resort to using custom routes. I try to avoid custom routes whenever possible - in my experience they lead to pain in the long run, more often than not.
- rajangdavis 8y ago
  Sinatra is awesome! Had a project recently where Active Record and Postgres with Sinatra made sense and it was completely painless. Rails _might_ have helped, but I have come to enjoy Sinatra's flexibility. Been debating about making something in between, but working on other things.
sureaboutthis 8y ago
Standardization is in place for interoperability issues, not management. Rules are NOT made to be broken, as you claim, and I see more people getting themselves into trouble for thinking that. This is computer science, not a game.
- coldtea 8y ago
  No, it's absolutely not "computer science". In fact the rules you talk of are totally ad hoc and/or cargo cult. At best, they're self-reported empirical (pre-scientific) findings. There's no systematic research that they're better than some alternative set of rules etc. People just adopt this or that framework or methodology (like REST) because some famous programmer wrote it or suggested it, some company promoted it, it picked up steam of GitHub and blogs, and so on. That's not only not "computer science", it's not even "software engineering".
mschaef 8y ago
> During development with Rails I struggled a lot, because it was forcing CRUD ideology ... This reminds me a bit of my first experiences with Common Lisp to write anything resembling serious code. (A Java compiler for my compilers class in school.) My education to that point had almost entirely been driven from a purely list based and functional view of the language. Instructors would default to lists at the expense of other data structures and strongly encourage 'non-destructive' operations at the expense of mutation. (Even the term 'destructive' carries with it an obvious negative and somewhat dangerous connotation.) Flash forward a couple semesters, and I'm trying to take this approach beyond writing simple unifiers and minimax search and apply it to a compiler with multiple layers of code that's being built up in phases over months. A month or so in, my resolve cracked, I started exploring some of the other options provided by the language (hash tables, vectors, mutation, etc.) and made a bunch more progress (and got something working by the end of the class). My point in saying this isn't really to advocate for mutation, etc., but rather to agree with your point that sometimes it's worth breaking out of self-imposed constraints so that you can face the external constraints that are probably more important. (ie: my business client probably doesn't give a damn if my RESTful interface is RMM level 2 or three as long as it lets her effectively run her business.) (One thing I'll add about the Lisp experience above is that it was more than half a lifetime ago... I'd probably be more nuanced with my use of mutation, etc. now than I was then. But then, I was much less experienced and a refugee from Pascal, etc. One of my constraints was my instructors' encouragements to avoid mutation... but another of my constraints was my own lack of techniques for working that way.)

chronicler 8y ago

I don't think anyone ever says RESTful services must be CRUD based, what they say is non-crud operations are hard to model in a RESTful service.

pas 8y ago

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 reified and URI-fied in the JSON.) > The workflow our API supports is more explicit, [...] Sure, that's pragmatic, but after much gnashing of teeth and scratching of heads, REST is about presenting options to the client by offering various media types (content-types), and letting the client request the best representation, and not really about a fixed ACL neither about fixed flow. From [1] again: "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]" [0] https://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post https://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post [1] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

dnomad 8y ago

filleokus 8y ago

After using GraphQL for over a year now I rarely miss the good old REST days. Certainly the declaration of schemas/models in the beginning is maybe more cumbersome compared to REST. But when that is in place is just so easy to work with, no more adding extra field in responses to avoid doing multiple unnecessary queries, just lovely. When mutating state with GraphQL the suggested approach seems to be to have "action based" endpoints, i.e "publishArticle", which resonates well with me.

jively 8y ago
My biggest issue with GraphQL is the fact that what essentially used to be a database operation has now become a (coordinated) batch API query. So the operation has been split into microservices, then re-joined using a GraphQL interpretation SPoF, all so that client business logic can be encapsulated as a query string, instead of securing that effort as a specialised API endpoint. Moving flexibility to the client comes with all the inherent risk of that flexibility being available to (in a browser sense) a risky client. RPC over REST is a solved problem IMO, arguments about REST RPC semantics become ideological after a while.
- rusk 8y ago
  > RPC over REST is a solved problem I'm interested in understanding more about this statement. Do you mean that all REST RPC libraries are sufficiently developed such that you don't really need to worry about RPC being tricky, or that we all just as a community understand the best strategies and common pitfalls. Or do you mean a specific technology? Just wondering cause whenever I hear the term RPC as an experience developer I just shudder (-: Thanks!
  - jively 8y ago
    I meant that there are well discussed strategies for handling calls that are RPC-oriented rather than CRUD, not that there are REST libraries that have solved the problem. Ultimately we find ourselves building 80-90% CRUD operations with edge cases that don’t entirely fit with the straightforward RESTful toolset, and in those situations making a call on how to handle it in code is a topic that has by now been more or less discussed to death and becomes a stylistic choice. REST isn’t a protocol, there is definitely interpretation at work. I was using the term “RPC” to cover topics that are outside the scope of CRUD, “do a thing” as opposed to “manipulate a thing”.

IshKebab 8y ago

REST is kind of a worthless term at this point because really nobody agrees on what it means. I'm sure somebody will reply saying "no it clearly means this!" or "it obviously means using HTTP how it was supposed to be used" or "those other people just don't understand REST", but the fact is we still have articles - in 2018! - that are trying to explain exactly what "REST" is.

LoSboccacc 8y ago
just because people don't understand doesn't mean everyone is wrong/right https://i.imgur.com/MCsxsAY.jpg https://i.imgur.com/MCsxsAY.jpg
- IshKebab 8y ago
  It means using the term "REST" for communication is useless - exactly like in that cartoon you linked.
jimjag 8y ago
If people don't agree with what it means, it's because they aren't spending time reading the actual dissertation. Instead they are kind of glancing over it and depending on others interpretations to create their own. As someone who writes protocol specs, Roy takes great care in being as clear as possible: confusion, inconsistency and misinterpretation are not Worthy Things in protocol implementations. To truly understand REST, you MUST understand HTTP and the rationale behind it.
- oftenwrong 8y ago
  Perhaps he should have written a specification for REST.
- dwaltrip 8y ago
  Words are defined by their usage, not by what one person thinks, even if they came up with the word.

fanf2 8y ago

The draft BCP56 revision, on the use of HTTP as a substrate, is a nice primer on REST API design https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis

nostalgeek 8y ago

It seems to me that REST "was never meant to solve web developers problems" at first place and that dissertation wasn't addressed to them. I'm glad we are getting out of REST. Devs need protocols and specifications, not vague architectural ideas that leads to "you're doing it wrong" blog posts. There is no "you're doing it wrong" with GraphQL, or SOAP, or JSON-RPC, you either follow the spec or you don't.

noir_lord 8y ago
I just use this https://labs.omniti.com/labs/jsend https://labs.omniti.com/labs/jsend and typed it up via TS. It makes for nice code. Promise<JSendApiResponse> With the benefit of HTTP level stuff not been mapped onto application level stuff. I like KISS with this kind of thing and if you need a more complex solution it handles that as a starting point.
- indexerror 8y ago
  You can do this with Axios too: interface IResponse { foo: string } async function doSomething() { const reponse: AxiosResponse<IResponse> = await Api.call() ... // or you can use AxiosPromise<IResponse> without the await }
organsnyder 8y ago
OpenAPI (née Swagger) helps a lot with this. While I'm sure that many purists would argue that you're not really doing REST if you have an OpenAPI contract, it certainly helps a lot with making APIs more usable to consumers.
bborud 8y ago
> Devs need protocols and specifications, not vague > architectural ideas that leads to "you're doing it wrong" > blog posts. This is precisely it. If an integration mechanism can't be implemented as a clear and uncomplicated library that strongly encourages correct use by making it the path of least resistance, it probably isn't any good. (And note that I said "library" rather than "framework". This is important as libraries are more like a thin layer of glue while framework is more like a metastasising cancer) Most of the time, REST, strictly speaking, demands too much attention even for relatively simple stuff, and therefore is not a good integration technology. However, some adaptations of REST are. The one thing that is a bit sad is that there is some nomenclature confusion. These days a REST API doesn't refer to Fielding's vision, but a more practical adaptation of the mechanical bits of it.

hirstys 8y ago

Hmmm, but is REST so often conflated with 'just' CRUD, because that is all people really want from REST, or is it that this perception is so pervasive that people don't know what the potential is. Chicken or Egg? I'm saying Egg, but I'm not saying which that relates to :)

clan 8y ago
CRUD is easy to understand and close to the core of tasks that programmers at large need to do. Thinking in terms of REST requires that you concern yourself about the full infrastructure. Many programmers i have met simply do not care. Super nice properties such as cacheable and discoverable are outside their domain. Most simply just want remote RPC. Try convincing a programmer of the benefits of HATEOAS is though. It will be dismissed as too much hassle with no real benefit. But if you look at it from a data architectural perspective everything just "clicks". Few projects are however approached from that angle.
- tjpnz 8y ago
  HATEOS can be a weighty concept to get across and it never clicked for me until I read a book on it. I still think there are aspects of it that could be learned easily enough in isolation though. Understanding media types for example allows you to develop some really nice schemes for API versioning. But few people are even willing to learn that and just butcher their URLs instead.

lmm 8y ago

The useful/valuable part of what came to be called "REST" (very little of which is found in the dissertation, it's an accident of terminology which has lead a lot of people astray) is all about CRUD, because CRUD is the only thing that makes sense to do with a generic "resource".

icebraining 8y ago
POST is used for way, way, way more than any CRUD operation.
- lmm 8y ago
  Indeed it is, but at that point it's not "REST".
  - icebraining 8y ago
    Why wouldn't it be?
    - lmm 8y ago
      The HTTP verb isn't reflecting what's happening, and likely some important considerations aren't being represented as entities.
      - icebraining 8y ago
        The description of the POST method is very generic; one of its functions detailed in the HTTP spec is: - Providing a block of data, such as the result of submitting a form, to a data-handling process; Which fits with much more than mere CRUD. And it's specifically written that it doesn't have to result in the creation of a new URI-addressable resource. (Also, REST isn't HTTP, you can comply with the former even if you're violating the latter, and vice-versa)
        lmm 8y ago

coldtea 8y ago

REST was never that good to begin with. (Not even as originally intended, which is very different from RESTful way 99% use it -- originally REST was all about self-reporting and discoverability, which is not used, and irrelevant to most use cases). Having JSON as the response, and a scheme to address entities, was good. Even using HTTP action semantics was OK (though debatable). But that's far from what REST is about. Something like JSON-RPC would be a much better for web API needs.

sureaboutthis 8y ago
That people misused REST is not what made REST "never that good" (in your opinion). In fact, it was this misuse that frustrated Dr. Fielding more than anything else.
- masklinn 8y ago
  > That people misused REST is not what made REST "never that good" (in your opinion). I used to be partial to that interpretation, but after a few years of looking at it, at what people do and at what's actually valuable, I've come to the conclusion that coldtea is correct: REST as originally intended was not that good for programmatic contexts. It certainly didn't help that it got quickly buzzwordified as "actually use HTTP properly instead of just shoving your garbage through POST all the time" (the original sin of SOAP or XML-RPC), but even then what makes "REST" work for browsers (which is what the concept was extracted from) is that there is an intelligent agent doing the discovery and driving the interaction. That's not useful for a programmatic API. You can add a discovery layer to a programmatic API (as e.g. graphql schemas & explorer tools) but requiring programmatic clients to go through such a discovery layer just makes interacting with the API painful for no value. Traversing a few pages when clicking around in your browser makes sense, doing so from a programmatic client when you could literally just store the correct endpoint and perform your call directly is nonsense: it's inefficient, it's annoying and it's pointlessly verbose. Yet that is essentially what proper rest as described and clarified[0] by Fielding require. Even the "multiple interpretations" (multiple content types) option is worthless when browsers don't provide the flexibility required to do content negotiation[1] or leverage HTTP verbs beyond GET and POST. [0] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... [1] even in places where they allow actual mimetypes it's as likely as not they'll ignore it e.g. object/@type is a mimetype but no browser I know cares about it, most of them send Accept: ∗/∗ and firefox sends its pagewise/default Accept.

sureaboutthis 8y ago

Many years ago, Dr. Fielding would visit a forum or two and offer answers to questions about REST. I had a number of my questions answered directly by him which helped me through the years to discover how many people have no clue about what REST is and how to use it but wave the REST flag as if they did--and they don't. I believe Roy quit visiting forums for those reasons; a frustration dealing with all that.

coldtea 8y ago
Words are not defined by their creators, they are defined by their usage. Those people indeed know what REST is -- in fact, they define what REST is. When we talk about REST, we talk about how people use it. They might not know what "REST as defined by Dr. Fielding is" but that's not really relevant to them or to the industry at large.
- nacnud 8y ago
  "use", not "usage". </joke>
  - coldtea 8y ago
    Not according to my dictionary: use: the action of using something or the state of being used for a purpose. usage: the action of using something or the fact of being used: a survey of water usage
    - itscaleb 8y ago
      Words are not defined by their creators, they are defined by their use. Those people indeed know what USAGE is -- in fact, they define what USAGE is. When we talk about USAGE, we talk about how people use it. They might not know what "USAGE as defined by coldtea is" but that's not really relevant to them or to the population at large. :-)
frederickf 8y ago
I'd love to read some of his original comments. Do you remember any of the threads? Are those forums publicly available?

billpg 8y ago

The way I think of it is that GET, PUT, PATCH and DELETE all deal with data, whereas POST is a call to action. It is a little unfortunate that we don't have a CREATE verb (distinct from the update-ness of PUT) and we need to use POST for this purpose.

0x445442 8y ago
That's interesting. Are you saying that you view Posts as verbs/processes which only result in side effects of the underlying system but do not change the state of data? I'm trying to understand what you would consider the domain of actions that would fall under your Post categorization. Batch Jobs, Emailing reports etc.?
- billpg 8y ago
  That's basically right. I view GET/PUT/PATCH/DELETE/CREATE as simple wrappers around SQL commands, with validation and authorization checks. POST is a call to do something with that data, which might include changing the data. Off the top of my head, logging in, actions with external systems, sending emails.
ams6110 8y ago
I've had to support http clients that could only do GET and POST. So I tend to do everything by those two verbs, even though it's not academically correct.

the_new_guy_29 8y ago

Only one thing about this article i have to say is that its posted on TERRIBLY designed page... Half of the screen black, align to the right and no "reading view".

hirstys 8y ago
Harsh but fair!? We're listening, feedback has been passed to the team who look after https://tyk.io/ https://tyk.io/.

lazulicurio 8y ago

I know it's not technically correct, but the conceptual definition I've found useful for myself is that REST is about operating on the HTTP layer instead of building your own layers on top of it. Why create your own custom error protocol when you can use HTTP error codes? Why develop your own caching strategy when you can use HTTP caching? Why create your own authentication mechanism when you can use HTTP authentication over TLS (or client certificates, or etc.)? When the article talks about how REST should be layered, cacheable, and client-agnostic, that's really the core of it to me. By thinking this way, you can see how REST helps you re-use already-existing infrastructure---proxies, load balancers, caches, etc.---instead of spending time and effort making custom solutions. It also helps provide guidance as to when REST may not be appropriate: can you answer those "why not HTTP?" questions? I've also found focusing on the resource/noun aspect (beyond considering caching) to be a bit of a "nerd trap"; it's possible to spend a lot of time chasing the perfect, "correct", solution. As the article notes, there's nothing wrong with "verby" URLs as long as you are using HTTP instead of doing your own thing.

osrec 8y ago
While I agree that we should not reinvent the wheel, caching data is often tricky with REST. In my experience, the caching aspect of HTTP can introduce unexpected behaviour into applications. To get round this, I see a lot of devs use POST requests for everything, and implement their own custom caching layer. Basically, I think HTTP caching is fine for files, but once you start working with complex data, things get cumbersome rather quickly.
- cxmnvcxkldn 8y ago
  What the actual problem with caching is, is personalisation. This has nothig to do with REST.
- organsnyder 8y ago
  For caching to work, you need to sit down—ideally with business stakeholders—and decide what the caching policy should be for each data element. For instance, in a healthcare domain, your core patient demographics—name, DOB, ethnicity, gender...—can likely have a fairly long TTL (perhaps even a day or more), since those attributes don't tend to change very often. However, something like a patient's list of upcoming appointments should have a very short TTL, since it changes more frequently. Once you've made those decisions from a business perspective, you can have your services send the HTTP headers to effect that caching behavior.

jstimpfle 8y ago

An idea that I've never heard expressed explicitly is how REST is basically distributed OOP. Both REST and OOP lead people to waste their time on unimportant questions.

beders 8y ago

The comments here show that there's still much confusion about REST being an architectural STYLE, not an actual architecture. If you can present your domain as addressable representations of resources and if you can lay out your business logic as changes to these resources, then you could use REST via HTTP to provide access to your service. Furthermore, if it is important to allow any client to connect to your service and you don't have any control over the clients used, then adopting HATEOAS provides a backward-compatible, future-proof way for client software to work with your service. If, OTOH, you have full control over the client-side, you can trade-off these abilities for a simpler model (like GraphQL, if you must, or simple RPC over HTTP) Know what you design for. Re Caching: Caching in HTTP is very flexible. E-Tags basically give you fine-grained control over how to cache and allow for significant bandwidth/performance improvement. However, in many cases your app will also benefit from an additional cache layer in your persistence layer. Don't confuse them.

mratzloff 8y ago

The main problem with REST is Roy Fielding's communication style. Here's a quote from a 2008 blog post: Apparently, I use words with too many syllables when comparing design trade-offs for network-based applications. I use too many general concepts, like hypertext, to describe REST instead of sticking to a concrete example, like HTML. I am supposed to tell them what they need to do, not how to think of the problem space. A few people even complained that my dissertation is too hard to read. Imagine that! Yeah, Roy. It's called being an effective communicator. Effective communicators include stories and concrete examples to help bring the audience along with them, instead of lengthy discussions of abstract concepts. Readers shouldn't have to perform exegesis on your slideshow and blog to get even a vague understanding of what you're trying to get at. To be clear, any difficulty with REST in practice is a direct result of an underspecified concept without a clearly defined RFC as it relates to HTTP. Fielding didn't define anything about REST in terms of HTTP. All of REST, as it relates to HTTP, has been an application of what other people think he meant. Nowhere in Fielding's 2002 academic paper[0], his 2008 talk at ApacheCon[1], or his blog[2] does Fielding have clear examples or thoughts on the kinds of specific details that Web developers often struggle with. Fielding, in my estimation, seems principally concerned with three things with regard to REST: 1) Every important resource has its own URI. 2) All interactions against that URI should be stateless and cacheable: all application state that is specific to the user should live on the client (e.g., local storage for browsers), and all shared state should live on the server. 3) Interaction with that URI should be the same regardless of client (browser, mobile app, etc.). Everything else is left as an exercise for the reader. [0] https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm [1] https://www.slideshare.net/royfielding/a-little-rest-and-relaxation https://www.slideshare.net/royfielding/a-little-rest-and-rel... [2] https://roy.gbiv.com/untangled/category/web-architecture https://roy.gbiv.com/untangled/category/web-architecture

MaxBarraclough 8y ago
> Readers shouldn't have to perform exegesis on your slideshow and blog to get even a vague understanding of what you're trying to get at. (Ironically?) I've found this same problem to be one of the best reasons to avoid WSDL/SOAP. Too much pie-in-the-sky waffle, not enough pragmatic real-life flavour.

ankurdhama 8y ago

The same old story with anything called "architecture patterns", you can look at them from different angles and each time you will have a new interpretation.

jillesvangurp 8y ago

Until AJAX happened around 2005, GET and POST were the only verbs you could actually use in a browser. Before then, REST was not a really a thing. It used to be that semantics of HTTP verbs had meaning in the context of e.g. caching and other middleware. But now that everybody uses TLS, having caching proxies acting as middlemen and interpreting http messages is not that common any more. REST was a nice idea when it got (re)invented about ten years after Fielding's thesis but it left too much open for debate, ambiguity, and nitpicking and quickly degenerated in different opinionated camps trying to retrofit new ideas to the existing practices around http, which mainly boiled down to interesting ways to do RPC. Before HTTP, people were already long doing RPC using e.g. DCOM, CORBA,RMI, etc. Reinveinting RPC over X has been the fate of pretty much every way we've come up with to make two computers talk to each other.

naasking 8y ago
> Before then, REST was not a really a thing. You only need GET and POST for REST. > Reinveinting RPC over X has been the fate of pretty much every way we've come up with to make two computers talk to each other. REST isn't just RPC, it's RPC with specific constraints to enable caching, scaling, adaptability, and distribution properties that unrestricted RPC alone cannot achieve. That's why REST is still important today, because RPC is too flexible, and RPC without constraints will inevitably run head first into all of the issues that REST solves for you. Unrestricted RPC libraries then let you "solve" these problems in myriad incompatible ways each with their own problems.
- habitue 8y ago
  > Unrestricted RPC libraries then let you "solve" these problems in myriad incompatible ways each with their own problems. I mean, this is exactly the state of REST today. It's not specified well enough to admit general purpose clients (like, for example, GraphQL does) because it's just a "pattern" not a specification. Because every API has its own way of doing paging, subresource expansion, expressing side-effectful operations, etc it means every API has a corresponding custom-built client. > Caching Do these custom clients implement http caching? Not usually. > Scaling Arguably, REST is responsible for bringing about the rise of stateless API servers. We should be grateful for the good idea, and not feel compelled to adhere to the other aspects of REST if they don't suit our purposes. > adaptability Claims of additional adaptability in REST are usually talking about HATEOAS where each resource defines how it can be interacted with by providing links and semantic metadata etc. I will flat out say it: this doesn't work. Short of building some intelligent agent into your API client, hypertext will never be the engine of application state in any meaningful way. You can't just change the links and have the client magically discover the right thing. Fielding's thesis was talking about the web, where humans are the ones deciding which links to follow. It's a useless concept in API design, and it adds tremendous overhead for zero benefit.

guhcampos 8y ago

I don't agree with the article (to me REST started about CRUD, and obviously got overloaded with time), but that's not what I need to comment. That font in the titles could have been gorgeous, but that upper case "D" is offendingly bad.

hirstys 8y ago
Ouch! Take your point, but don't you think the feels you get from the lower case "about" in the title makes up for any failing in the "D"?

OldSchoolJohnny 8y ago

Half the page is a calendar widget?! This is the worst layout I've seen in a long time.

hirstys 8y ago
Harsh criticism Johnny! But we'll take it on board, feedback has been passed to the https://tyk.io/ https://tyk.io/ team, there is certainly an opportunity to adjust proportions here. As a matter of interest, which blog/article page layout do you really rate?
- OldSchoolJohnny 8y ago
  I think I was that emphatic because I couldn't believe anyone would want to exhibit such an obviously flawed design in public until it was fixed. I'm still confused how this would make the light of day, but I guess esthetics and usability are something learned perhaps over time?

niftich 8y ago

REST as seen in HTTP has always been about resources (identified by URLs), representations thereof that take the form of a particular mediatype (selected explicitly or by content negotiation), and hyperlinks (with targets and rels). When resources are obvious nouns already present in the backend's data model, this maps well to CRUD. The problem comes when trying to describe complex mutations, because to most people, this feels wrong, instilled by years of Dos and Don'ts of half-baked lessons about Object Oriented design. In all this time between when Roy's thesis was rediscovered to promote an architectural style and when the trendiness of REST has finally run its course, there were far too many posts complaining about deployments missing hyperlinks (when usually, the API was externally documented, URLs templated, and its clients hardcoded, making many usecases of embedded hyperlinks moot), and not enough to reassure flummoxed designers that naming resources after verbal nouns or deverbal nouns is perfectly fine. Oops.

mi100hael 8y ago

I disagree with the article and the examples provided. The author has left out a few key components of REST in their initial distillation. Critically: > REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. So given the example from the article: POST /articles/{articleId}/approve This URL does not point to a resource, and the HTTP verb does not describe what action is being taken upon a resource. It's also not using the representation of a resource to capture intent. It's also worth noting that a GET for the article would return the "status" field and presumably other PUT requests to update the article would either act directly on the article or have other vanity action URLs, making the API more verbose than if everything were done properly. A RESTful design would be in essence CRUD. It would have a url (/articles/{articleId}) identifying a resource, it would have a representation of a resource that includes a "status" field, and changing the status of the article would involve a PUT request to the URL of the article with the desired change of state.

macca321 8y ago
It's a "request to approve an article" resource, even if it hasn't explicitly been modelled that way.
- mi100hael 8y ago
  By that logic, SOAP is RESTful.
draw_down 8y ago
Oh my god just freakin kill me already. You can never do this shit right, it’s extremely tedious.

lloeki 8y ago

The author proposes: POST /articles/{articleId}/submit POST /articles/{articleId}/approve POST /articles/{articleId}/decline POST /articles/{articleId}/publish I find this troublesome because the URL path component then includes a verb, an action, so there are two verbs in the same sentence! This can be adjusted to: POST /articles/{articleId}/submitted POST /articles/{articleId}/approved POST /articles/{articleId}/declined POST /articles/{articleId}/published Now the URLs really represent resources on which HTTP verbs operate, and you can readily guess what GET (if needed/applicable) on each resource would give you. There is some cognitive dissonance introduced by the inconsistency of abstraction levels between the former "RPC style" (where HTTP verbs are mere actuators† and the intent is in the URL and/or in the payload), and the latter "REST style" (where verbs carry intent acted upon resources). EDIT: I do not advocate for one over the other, merely that an API should be consistent overall and not mix both. † They are used as pure HTTP feature control (like caching) and do not carry application-level semantics.

rhacker 8y ago

I've been a long time fan of what this article is saying - but I didn't know it was a thing. Now if I ever run into CRUDdy teams, I have something to share with them :)

zzbzq 8y ago

Despite the architectural principals, it's named REST--REpresentational State Transfer. It's really hard to twist and contrive a situation in which "REpresentational State" is not CRUD. It can be done, but it's awkward. As soon as you're doing non-CRUD operations, it's really hard to model them as representations of state, and it's sometimes very unpleasant to use APIs where the designers tried too hard to make the peg fit.

coding123 8y ago

My main gripe with REST is that it's totally not future proof. The notion of RPC has been around forever. REST has basically completely replaced that. Http status codes and REST URLs are not future proof. We have already seen superior connection types (web sockets) come (and then basically go) that don't support the notion of URLs and (well they do for a second, but after that the original connection the URL is meaningless for the traffic flow). With Http2 we're seeing the return of lightweight connections (basically similar to websockets but have more graceful re-connection options). But http2 feels like a patch to me. I don't really want to bind the future of Apps to a bunch of URLs. I'd rather tie my app to a client that has a rich semantic set of objects and methods that pull down data, can update data, etc... When we use REST as our layer to convey the API itself, we really lock ourselves down to a very specific set of URLs and HTTP Status codes. I'd rather have a rich error object thrown, not an HTTP status code that I have to examine. I've had a pretty strong disdain for REST for the last few years and have been actively finding replacements. The closest I can come up with is Grpc. I'm dying waiting for Google to finish up Grpc-web however. If we continue to tie ourselves to a bunch of server resources by URL we're going to take forever to get off this archaic system that has no long term future.

ako 8y ago
Do you think the web could have been built with RPC instead, and be just as successful?

didibus 8y ago

I'd like to implement such and API, but I feel often time its not that we don't want to design an API that way, but that we fail to successfully implement one. I'd like to hear about guidelines, like for that transaction workflow example, how would you implement this? What would be your data model?