18 ms·

Problems with RESTful APIs (2015)

• codr4life 10y ago
  I'm going to have to call bullshit on that one. REST is one of the more successful strategies we've come up with for connecting systems, this is just another case of letting perfect stand in the way of good enough. Using GET for non-destructive operations and POST for updates and deletes is a nice, portable compromise. I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not worth the effort.
  • RubenSandwich 10y ago
    It is considered best practice to separate out POST and PUT by PUT being idempotent while POST is not: https://stackoverflow.com/questions/18485621/what-is-meant-by-put-method-idempotent-in-restful-web-service https://stackoverflow.com/questions/18485621/what-is-meant-b.... This allows you to reason better about API calls in code by their HTTP method without having to check the fields sent.
  • rantanplan 10y ago
    > I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not worth the effort. And right there, at your final sentence, you basically described why REST has more or less failed. GET and POST are useless for implementing a complete application protocol. You'd basically overload these http verbs to the point where you would implement your own protocol. And that's what most people do anyway. You choose to not use PUT, some other person chooses to not use PATCH or HEAD and I choose to curse vehemently every time I have to use someone's service. REST is nothing but loosely connected guidelines that nobody uses in the same manner.
    • WillPostForFood 10y ago
      Maybe it is fair to call REST a failure in that it is flawed, and there aren't perfect implementations. But I just had to go through a SOAP XML integration, and it was ten times more painful than the worst REST experience I've had. So I still see REST as one of the biggest tech wins in a long time.
      • rantanplan 10y ago
        Ouch. You brought a gun to a fist fight. Ok ok, SOAP/XML apis are worse. Agreed.
      • edejong 10y ago
        Really? I made one yesterday based on a WSDL from a customer. The whole API was auto generated in type safe Scala in seconds. After adding authentication configuration and some sensible timeouts, I had the whole thing running in two hours. The SOAPui auto generated a mock test and load tests with which I could mimic specific weird responses. The REST API I had to forward through however had no good documentation, no client library, so I was forced to write json serializers and reverse engineer the code. Overall, when you have a well written SOAP interface (rare, admitted), development time can be greatly reduced.
        • thehardsphere 10y ago
          In order to get the well written SOAP interface, it helps to have the right tools and be used to using them. I think that increases the barrier to entry on using SOAP, which leads to the idea that SOAP is terrible and crufty compared to REST. I learned SOAP relatively recently, but well after it was a fad. Today, my experience would be like yours if I had to make a SOAP service with just a WSDL. But when I started out? It would take a longer for me to wrap my head around all of it. I can't imagine how confusing it would be if I had to do it all without the benefit of working on a team whose focus is a SOAP-based product. I dunno if I would know where to begin. Compare that to REST. Even if you know next-to-nothing to start, you can do a basic REST tutorial for just about any stack in an hour, and get a basic implementation of an API up in an afternoon.
        • user15672 10y ago
          Did you really just complain that REST is bad because you couldn't find an auto-generation tool to do your work for you? Because that's hilarious. Also, you don't seem to have looked terribly hard, because there are a few really powerful tools out there for autogenerating server and client code for REST APIs, as well as mock servers and a whole host of other tooling (See: Swagger, RAML, API Blueprint for starting points).
    • dandelany 10y ago
      REST has "failed" in the same way that many original visions of the web/APIs/protocols have "failed" - you have a few "no-true-Scotsman" purists complaining about differences in implementation; meanwhile a great many real-world developers are quite happy and productive in a REST-like paradigm and don't particularly care that their API doesn't fit some Platonic ideal. Could things be better? No doubt. But REST (or something like it) is largely "the way things are built" these days and most people don't mind. Calling it a failure is quite a stretch IMO.
      • rantanplan 10y ago
        Your comparisons are not that relevant. Also comparing it to a "protocol" is the overstatement of the decade. How many browsers do you have? 3-5? How many REST client libraries are there? Answer: one per service(per programming language). What kind of protocol is that?
        • dandelany 10y ago
          I'm not claiming that REST is a protocol. I'm saying that the de facto state of the REST paradigm today is analogous to some protocols which have been twisted to support use-cases far beyond what their designers intended, in ways that make purists squeamish, but make developers happy that their shit works.
          • rantanplan 10y ago
            > use-cases far beyond what their designers intended OK, I get what you're saying. Problem is that as far as I can see REST is perfect for S3-like services, Maps(?) and slightly more than basic CRUD applications. You are bound to discover its limits very soon. The gazillions of books and blogposts out there heralding it as a serious interface are not helping either. BTW, I don't know about other people criticizing, I am definitely not a purist. But after ~10 years of dealing with REST in various capacities(startups to Enterprises), I am a bit tired and can't wait for something to replace it.
    • codr4life 10y ago
      It failed? When?
    • naasking 10y ago
      > As the article points out, there are all too many HTTP libraries that only support GET and POST, not the more "esoteric" verbs like PUT and DELETE. GET and POST are all you need: "Return representation of available operations" and "apply this operation". It's the lambda calculus applied to the web (see Waterken's web-calculus for a more formal treatment). You might say that this is too anemic a foundation and you want more built into the protocol level to handle some common tasks, but I'm not convinced it's necessary or even desirable. At some point requirements will change and some of those tasks will be supplanted, but we'll have to live with them forever if we bake it into the protocol.
      • rantanplan 10y ago
        You're just supporting my argument and weakening REST's case. I can do you one better. If you managed to reduce everything down to GET and POST here's an idea; just use POST for everything. Boom. You just re-invented SOAP.
        • naasking 10y ago
          > You're just supporting my argument and weakening REST's case. How? Perhaps you should actually elaborate your argument. REST doesn't depend on the use of verbs, it's an architecture that elaborates the requirements for object designation (URLs), object lifetimes (statelessness) and hypermedia-driven service discovery (HATEOAS). Only GET and POST in HTTP are required to fulfill these requirements. If there's actually something wrong with that, then lay it out. > If you managed to reduce everything down to GET and POST here's an idea; just use POST for everything. Boom. You just re-invented SOAP Except you can't in a world with side-effects. You could do exactly what you say if every POST were guaranteed to be idempotent. Every request could carry a full payload like a POST request and a unique identifier to ensure at-most-once semantics. That would be a fine protocol, and totally REST compatible. What's the problem exactly? Finally, SOAP carries far more baggage than you imply. It's a false equivalency.
          • rantanplan 10y ago
            It's not a false equivalency. Books have been written about it and describe how you defeat REST by doing what you describe. When you encapsulate most of your operations under POST you basically create your arbitrary protocol. No assumptions can be made about your service. You can make your own assumptions about your own service, but the others can't. > That would be a fine protocol, and totally REST compatible. What's the problem exactly? The problem would be that it wouldn't be REST compatible. You should clearly read a few books on the subject. Friendly advice, not a snarky comment. REST already has idempotent mutating operations, like PUT and DELETE. It's not just GET that's idempotent. So clearly the problem is that you redefine your own protocol, with your own semantics, even though we already have plenty of standardized methods/response codes. > If there's actually something wrong with that, then lay it out. You have obviously missed a ton of bibliography on the subject. Before reading random blog posts from random people who have their arbitrary assumptions about what REST is, I'd suggest reading a few books on the subject. Honestly sorry if I sound snarky, but after 10 years on working with such APIs, and after reading countless books on the subject, it never ceases to amaze me how people still think that GET and POST are enough. But I don't blame you, but the browsers who basically broke the protocol by just using those 2.
    • problems 10y ago
      Exactly. The whole "RESTful APIs" thing never was - I've been saying this since I first heard the term used. It's not a standard, just HTTP APIs, implemented wildly. Nothing wrong with that, but don't call it a standard and don't try to name it something it isn't.
    • throwaway5752 10y ago
      > "REST is nothing but loosely connected guidelines that nobody uses in the same manner" But is that really a huge problem? Look at more rigorous rpc standards with more rigorous standards and formal interface definitions: RMI, xmlrpc, CORBA, SOAP, Thrift, AMF... I'm sure there are loads and loads of real world systems using these and they have their place, but REST has succeeded in a large niche that they have not.
      • toyg 10y ago
        That's really the winning point of REST: it's just formal enough to put most people on the same page, and loose enough to adapt to different requirements without too much effort. It's useful to remember that REST was borne and adopted mostly in reaction to SOAP and XMLRPC (which in turn were basically replacing CORBA and RMI to work around the firewall). XMLRPC was too loose, and SOAP was too formal (way too formal). REST hit the sweet spot. However, it's sad that the result was often that people just retooled their crappy SOAP / RPC systems to use decent URLs and called it REST. My litmus test is usually "returning 200 OK on all calls" - if you're doing that, that's not REST. Use proper HTTP return codes and put additional error messages in the payload, it's not hard. Also, if you have a job queue, give each job a URL with the ID and GET that to retrieve status.
    • LoSboccacc 10y ago
      Rest is a well defined semantic everybody bastardized because they find shameful to say they use json-rpc on the resume or elsewhere. There's a difference there.
      • deleted 10y ago
        [deleted]
    • theprotocol 10y ago
      >REST is nothing but loosely connected guidelines that nobody uses in the same manner. I don't see a problem with this. In fact, I'd love it if everyone accepted this instead of whining that something isn't truly "RESTful." For instance, the app I'm working on deliberately does not implement HATEOAS. I appreciate the academic effort behind REST and RESTfulness, but ultimately I view it only as an ideal to tend toward. As you said, it's a guideline.
  • andybak 10y ago
    What you just described is only the bare shell of REST. It would also apply to many types of API that don't follow REST principles. One thing this article gets right is that nobody is really RESTful because nobody knows what it means. There's usually a dollop of RPC in most APIs - and there's nothing wrong with that - but the 'pure vision' of REST is similar to the 'pure vision' of the Semantic Web. It's a dream for the next life not something we will receive in this one.
    • codr4life 10y ago
      I'm fine with using ideas that make sense and rejecting the ones that don't. It's still solid advice for API design, and the most successful approach we've come up with. Doing REST to the letter always turns into some kind of modern art installation with lots of hammers looking for nails; this is the technology department, religion is down the corridor. I have full confidence that the authors considered these ideas, not laws.
      • masklinn 10y ago
        So… why do you call it REST rather than just HTTP since that's exactly what it is? You're using GET and POST for what they were built for, great, that's just HTTP, why not call it that? > I have full confidence that the authors considered these ideas, not laws. "The authors" considered hyperlinking to be the one core concept of REST, all the rest is just fluff/transport concerns: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... (that's the bloke who wrote the original REST paper). That's like saying the authors of the word "bicycle" considered it being two wheeled idea, not law, and you'll call your 8-wheeled ATV a bicycle because it has wheels and you think wheels are nice and solve your problem and the religion department is down the corridor. Yeah wheels are nice and solve your problem, your motorised monstrosity is not a bicycle though.
        • scaryclam 10y ago
          I'm leaning more and more in the direction of ditching the term "REST API" and just saying our APIs are Web or HTTP APIs. I'm beginning to think people just say REST API because it looks better on their CV, not because its helpful to other developers who may end up using it.
  • alganet 10y ago
    You don't need PUT nor DELETE. It is OK to use POST[1]. Most people don't understand REST. It is not a standard, it is not a set of practices. It is an architectural style and the web is built on it. You can choose to follow the style (which is so much more than naming methods and URIs) or fight it. The dissertation is pretty clear about it[2], but most people ignore it because there are no code samples. [1]: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post (REST creator talking about the PUT misconception) [2]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm (Full REST dissertation)
    • coldtea 10y ago
      >You can choose to follow the style (which is so much more than naming methods and URIs) or fight it. And most people chose to ignore it -- and implement RESTful (mostly unrelated to REST as described by Roy) APIs, and no much harm has befallen them.
      • alganet 10y ago
        Ignoring the dissertation is OK. It was designed for people to understand how the web was designed, not as an implementation guide. Ignoring REST is impossible, the web is built on it. - The uniform interface is in every URI (if you use them, you use REST). - The code-on-demand constraint is everywhere (if you use JavaScript, you're using REST). - Hypermedia is everywhere (if you have links on your web page, you're using REST). - The client-server constraint I don't even have to bother explaining (although WebRTC might bring P2P back in the game). - The layering is everywhere (if you do haproxy, varnish, squid or similar, your using REST). The _RESTful API_ thing is just a myth. People needed a name to discourage tunneling RPCs over HTTP, so they invented these loosely defined terms to push the idea. It should be called HTTPful, because it tells more about avoiding re-implementing HTTP features than it tells about the REST style.
        • deleted 10y ago
          [deleted]
  • lcw 10y ago
    Although PUT is not necessary using it for idempotent calls like it was designed to do actually helps developers using the API understand the intent of the call better. They don't have to worry about undesired consequences/side effects. Which I think is a useful pattern.
    • codr4life 10y ago
      I agree that it's potentially useful, but it also adds it's share of complexity to any implementation I've come across. And most proposed uses I've seen do not obviously benefit from the idempotent approach, from my experience it often complicates the server implementation. I've found using the REST approach for URLs, separating reads from writes and using status codes a good compromise.
    • naasking 10y ago
      > Although PUT is not necessary using it for idempotent calls like it was designed to do actually helps developers using the API understand the intent of the call better. They don't have to worry about undesired consequences/side effects. This can also be solved by futures. Any POST that you'd like to retry, which will be any of them given the unpredictability of network partitions, can be bound to a future so the operation is applied only once and all future attempts simply return the bound value.
      • int_19h 10y ago
        The point of having something like PUT (that is known to be imdepotent) is that it can be retried by any of the layers in the stack, instead of having a full roundtrip back to the client on every retry. And it's not always safe to retry POSTs. If POST is an insert, for example, retrying it would produce two inserts. And this can have interesting consequences when processing responses. Suppose that you have sent a POST request, but before you could read the response, connection dropped. You didn't get a chance to read the status code, so you don't know if your insert succeeded or not. If it didn't, you want to retry - but you'll need to do a GET first to check the current state of affairs. OTOH, if you're doing a PUT, you can just retry immediately without re-checking.
  • coldtea 10y ago
    >I'm going to have to call bullshit on that one. And yet you don't provide a single concrete reason. And even go on to say the non-REST way you use REST at your team. >REST is one of the more successful strategies we've come up with for connecting systems, this is just another case of letting perfect stand in the way of good enough. Using GET for non-destructive operations and POST for updates and deletes is a nice, portable compromise. I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not worth the effort. Note how none of this (or even few parts of what the author of TFA described) is actually REST as defined by Roy.
    • codr4life 10y ago
      You might do well to read what I wrote about perfect and good enough. These are ideas, not laws.
      • Avernar 10y ago
        Taking ideas from REST and putting it into your JSON-RPC API doesn't make your API REST. But you call it REST anyways. It's like reading a book on building a house and using ideas to build a shed. Sure your shed has electricity and a sink but it's still a shed, not a house. Same with terms like RESTful. You don't call your shed a "house like building" as it's missing key pieces of a house. REST requires HATEOAS. The only real implementation is the world wide web. Everything else is really JSON-RPC or some other protocol with a few ideas borrowed from REST.
  • LoSboccacc 10y ago
    Http-rpc is. People call it rest nowadays even when it isn't nor understand the state tranfer part of rest. Not saying it's your case specifically but I'we seen exactly zero http-rpc API implementing rest but a shitton people claiming their json-rpc interface was.
  • dragonwriter 10y ago
    PUT is for the case where the client knows the location of the resource to be created, whereas POST is for the case where all that is known is the location of a logical parent resource.
• joatmon-snoo 10y ago
  This reminds me a lot of Bret Victor's "The Future of Programming". https://www.youtube.com/watch?v=8pTEmbeENF4 https://www.youtube.com/watch?v=8pTEmbeENF4
• derefr 10y ago
  The "true spirit" of REST, to me, is that there's a certain set of things you can do when creating an API that will let you re-use the huge amount of HTTP middleware that's been written and get correct (and useful!) semantics from it. Caches (browser-, edge-, and server-side-), load balancers, forward- and reverse-proxies, application-layer firewalls, etc. will all "just work" for your software if you do REST correctly, and won't have any weird edge-cases. Re-implementing those same semantics in your own messaging protocol / format, without intertwining the concerns of the protocol and the message format, throws away any/all of those benefits. You need a protocol that guarantees that middleware can "look inside" the messages it's passing (or at least their metadata), in order for any of this to work. That's why HTTP has both a transparent part (req path+headers; resp status code) and an opaque part (req and resp bodies) to each message: the transparent part is there for data that affects middleware behavior, while the opaque part is there for data that doesn't. Note that that doesn't mean you're stuck with HTTP1. SPDY/HTTP2 is effectively an entirely different protocol—but it keeps the same semantics of requiring certain properties of the metadata tagged onto each message at the protocol level, so that anything that speaks the protocol can use that metadata to inform its decisions.
  • quanticle 10y ago
    The "true spirit" of REST, to me, is that there's a certain set of things you can do when creating an API that will let you re-use the huge amount of HTTP middleware that's been written and get correct (and useful!) semantics from it. Caches (browser-, edge-, and server-side-), load balancers, forward- and reverse-proxies, application-layer firewalls, etc. will all "just work" for your software if you do REST correctly, and won't have any weird edge-cases. Doesn't that assume that the middleware also implements REST correctly? As the article points out, there are all too many HTTP libraries that only support GET and POST, not the more "esoteric" verbs like PUT and DELETE.
    • dragonwriter 10y ago
      > Doesn't that assume that the middleware also implements REST correctly? It assumes that the middleware supports HTTP properly.
• notfed 10y ago
  "For example, most web browsers have limited support for PUT or DELETE." Um...is this guy trying to implement REST clients with HTML forms? Does he know about ajax? Fact check: http://stackoverflow.com/questions/165779/are-the-put-delete-head-etc-methods-available-in-most-web-browsers http://stackoverflow.com/questions/165779/are-the-put-delete...
• rs86 10y ago
  I liked that the article made me think of using websockets for a pure JSON API, but I think it misses a lot of what is nice about rest and much of what it criticises is actually HTTP..... Rest as a set of verbs that act on resources is really useful. I used to find it awkward to implement services in rest, as in some action that is triggered and may overlive the request cycle until I started thinking of service commands as items in a work queue that get processed by a worker. So when a service is requested I can see it as a resource being created.
• teddyh 10y ago
  In my opinion, you can't really understand REST until you understand HATEOAS - the two concepts work together and REST (and the restrictions it imposes) isn't really very meaningful without HATEOAS. Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is Wrong: http://vimeo.com/30764565 http://vimeo.com/30764565 REST APIs must be hypertext-driven: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... Hypermedia APIs - Jon Moore: http://vimeo.com/20781278 http://vimeo.com/20781278 Designing a RESTful Web API: http://blog.luisrei.com/articles/rest.html http://blog.luisrei.com/articles/rest.html
  • jpulec 10y ago
    Came here looking for a comment like this. If you're not discussing HATEOAS at all, you will be losing out on many of the benefits that REST provides.
    • dfsegoat 10y ago
      It's the 'central dogma' of RESTful services.
  • edwinyzh 10y ago
    The first time I heard about HATEOAS is from the authoer of intercooler.js, and these tow of his blog posts were insiprable: HATEOAS is for Humans :(http://intercoolerjs.org/2016/01/18/rescuing-rest.html http://intercoolerjs.org/2016/01/18/rescuing-rest.html) Rescuing REST From the API Winter: (http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.ht...)
  • vinceguidry 10y ago
    From your second link: > A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. I'm not getting it. We have an API layer serving both mobile and web clients. When we change the API layer, we have to be careful to not remove any fields willy-nilly that mobile might be using. Instead we hard-deprecate mobile versions and remove fields later. It keeps the application stable but makes future architecture depend on past architecture. Server instruction on URL construction seems to be doing a lot of work in order to not fix the problem. It does not buy us the ability to just switch around field names and relations and hierarchy without concerns for what consumers were using the old system. That's the real problem with server / client coupling, not that the client needs to magically know which route a created resource has. Sticking a link in the response body just seems silly. Without reinventing SOAP in JSON form, by this I mean providing machine-readable schema information via the API, I can't see a way through this. But even that wouldn't solve the problem, you'd need some kind of intelligence on the client side for managing an API that might shift around under it without warning. If we change a field from createdDate to createDate, is there a way to use HATEOAS to communicate the name change?
• jquast 10y ago
  I think what bothers me most about REST is that the endpoint is not sufficient to get started. The schema is never known. I hate SOAP and xml-rpc, but at least you can know for sure what endpoints, parameters, and variable types are appropriate. With REST, you must have documentation or source code of the service you communicate with, they offer no discoverability. I won't use REST again. I got an opportunity to use GraphQL recently in my profession and all of my projects will be using it in the future.
  • teddyh 10y ago
    REST without using hypertext data types is indeed non-discoverable. You have experienced why REST is almost pointless without HATEOAS. Next time, look into using REST with HATEOAS, as it was intended to be used.
    • jquast 10y ago
      Previously using HATEOAS, gathering large amounts of data, say some kind of reporting dashboard, required a great deal of seperate HTTP requests, it was far less efficient in I/O and performance than without. Anyway, I find GraphQL provides this solution very kindly, I can ask questions about the great big world, and request only specific fields, like a user's name, the names of their 10 closest friends and their availability status, all in a single call. With HATEOAS this could be 10 to 20 calls, and maybe contain extra information in the response I'm not necessarily interested in.
      • other_herbert 10y ago
        I was looking for someone to mention graphql... For lots of cases this is a great way to reduce the client calls and give the client exactly what it is asking for..
  • dragonwriter 10y ago
    > I think what bothers me most about REST is that the endpoint is not sufficient to get started. The schema is never known. If you are actually doing REST, the interpretation of a resource representation is fully specified by the media-type (insofar as if there is additional schema, etc., information necessary, how to find that given the actual representation is also defined by the media type.) Obviously, this is not true in the all-to-common REST-minus-HATEOAS.
• bradmwalker 10y ago
  REST: JSON CRUD over HTTP https://youtube.com/watch?v=oVE6OF-d1oQ#t=02m02s https://youtube.com/watch?v=oVE6OF-d1oQ#t=02m02s
• fleitz 10y ago
  Here's the rub, you're completely right, the problem is for the most part when you don't have rockstars making JSON Pure APIs you end up with half of HTTP redone in some god awful manner. I once worked with an API where they implemented their own HTTPS and because their own https didn't support gzip they removed quotes from json keys to save bandwidth. JSON pure probably is better when working with knowledgeable people but REST is better than what most people come up with and when not following REST
• gkoberger 10y ago
  The promise of APIs is simple. Send some data, something happens, get some data back. But at about hour 4 of wrangling a bearer token to authenticate your barely-documentated PATCH request that is returning a strange error about your application/x-www-form-urlencoded body, you start to realize that APIs in theory are very different from APIs in practice. (That being said, I don't love the "solution". It's very simplistic and it seems like the author doesn't really understand what he dislike about APIs. I don't think we need another protocol, but rather higher-level tools for dealing with them.)
• ads1018 10y ago
  (ahem!) graphql
• davidhariri 10y ago
  The author has some good points, but they're drowned in exaggeration and dogma.
• ravibala1 10y ago
  Seems like most of the comments hate on REST because it's been poorly implemented by an API developer. Why is the solution yet another API protocol (JSONpure) and not stricter enforcement? (Idealistic i know...) The point about SOAP not requiring documentation makes no sense either. You'd still need to document what the underlying fields in the various endpoints are. (We build against a lot of terribly documented SOAP APIs and its pure torture) In terms of PUT (and PATCH) not being extensively used - it comes down to your use case. For the idempotent micro-services we build APIs against, there is a massive difference in the behavior expected for POST/PUT/PATCH and it would be pretty burdensome (and limiting) to have to create parsing code on the server for POST.
• awinder 10y ago
  Ever notice how nobody calls their API “RESTpure”? Instead they call it “RESTful” or “RESTish”. That’s because nobody can agree on what all the methods, payloads, and response codes really mean. These reasons have nothing to do with why people don't use the term "REST" versus using "RESTful". RESTful is the compromised approach, cribbing some of the concepts outlined in Fielding's paper but dispensing with others. Among those are a de-emphasis of linking, and a url naming pattern. HTTP verbs describe types of actions in RESTful lingo, versus meaning something about the different idempotency & safety guarantees of a request in the REST paper. In REST, I'm not sure that a lot of these issues are that contentious. I do think that some of the emphasized points in "RESTful" design practice can create more contention in API design, but that's the downfall of that one pattern, it has nothing to do with what Fielding described. No governing body - at least to my knowledge - has convened to set things straight IANA has a ton of info on link relations and they're thoroughly speced. IETF has tons of API / REST related specifications. Profiles allow for defining what your data means, there's open source curated lists of these profiles already so if you were designing an API you could even leverage existing works to make your design easier. Roy is probably a great guy and he certainly had a lot of great ideas. However, I don’t believe that RESTful APIs was one of them. This statement is just downright hysterical given the relative disparity here. So much of the web is owed to Fielding's paper, there's been countless books and blog posts and just human man hours devoted to the work he's done. Who's this guy? Why is this such a trend in blog posts in this community, it just looks foolish and comes off as petty...
  • ianai 10y ago
    How accurate are those curated lists?
• Manishearth 10y ago
  > Ever notice how nobody calls their API “RESTpure”? Instead they call it “RESTful” or “RESTish”. Isn't that just because RESTful is a play on words? > For example, most web browsers have limited support for PUT or DELETE. Really? How? If anything browsers restrict these methods to exactly how they should be used (DELETE can't have postdata but PUT can). It's true that folks don't use PUT/DELETE much (the alternative works perfectly well though), but to me that's because they're unnecessary complexity, not browser support.
• metafunctor 10y ago
  The proposed way forward appears to be just discarding all of the common, reusable, standard forms we have started to build with HTTP. JSON-Pure is not much more than an encoding. RESTful is an entire protocol.
• toadkicker 10y ago
  In the second article the author explains what a 'JSON pure' api would function. It completely throws out the OSI model and provides no way for the application layer to react to transmission errors, which HTTP codes provide.
• elastic_church 10y ago
  (2015) but timeless
• debaserab2 10y ago
  Most of the problems described with REST in this article are examples of REST implemented improperly. We've had years to get it right; things like HTTP verb support, debugging, discoverability are all by and large a solved problem. The one point that stands is that it is deeply tied to HTTP, but I consider that to be a positive: a well designed REST API means the message is only about the content of what it's serving and not about negotiation of that content. Here in the "JSON Pure API" you see a reinvention of HTTP request and response concepts built into the API payload, leaving the implementation of negotiation up to the consumer of the API. You lose all the benefits of years of development that have gone into browsers and web servers to handle this for you. The main problem with REST is that people tend to call any JSON endpoint they build a REST API (and hence the term, "RESTful") which leads to a misunderstanding of what REST actually is.
  • psadauskas 10y ago
    Right, there's a great many blog posts that can be TL;DRed as "We implemented REST wrong, and it didn't work. I guess REST is overrated." There's two major components that makes an API truly REST, as opposed to the XML-RPC and SOAP-style APIs that were popular in the early 2000s: Proper use of the HTTP verbs, and the use of Hypermedia. Most so-called RESTful APIs have adopted the verbs part of it successfully and correctly, but the vast majority have completely whiffed on hypermedia. Your HTTP API is a state machine whether you like it or not. Hypermedia gives you a means to describe the state transitions as a part of your API. Without it, you are essentially requiring each of your API consumers to re-implement the state transitions for themselves. (The aggravating part of that, however, is that there's not too many good hypermedia-based client libraries, because it seems that most of the proponents would prefer to navel-gaze in their ivory towers, thinking about RFCs and getting the standards perfect. But I digress.) I wrote a blog post a few months back that goes into more detail about the advantages conferred by a true Hypermedia API: http://blog.theamazingrando.com/in-band-vs-out-of-band.html http://blog.theamazingrando.com/in-band-vs-out-of-band.html
    • int_19h 10y ago
      I'm not sure I see the advantages. It's a lot more verbose, based on the few examples I'm seeing there, and strongly reminds me of SOAP, XML Schema, and the rest of that over-complicated stack. I suppose some amount of complication would be fine if the benefits were clear, but I feel like I could implement a client and a server for the less-verbose API that you start with, in the amount of time it would take to implement a server alone with all those bells and whistles. And I can't think of any scenario where they would actually add value. I think the reason why RESTful APIs with very simple JSON payloads became so popular is because they get the job done with so little effort and so few abstract concepts to grok. This feels like a step backwards in that respect.
• weixiyen 10y ago
  New mobile-first products should consider GraphQL over REST. There's a lot of benefits that you will probably end up doing yourself in a bastardized version of REST anyways, like field restrictions and multiplexing multiple unrelated data requests over the same network call. GraphQL handles these cases elegantly.
• AngeloAnolin 10y ago
  Did I missed something on the article, whereas, I was hoping that it would expound on why REST should not be trusted. A title more apt would be: "REST is totally flawed" or something similar. Saying REST is a big lie is somewhat misleading, when the overall context of what it is and what it should be is still up for debate. Does it matter when you can't completely and fully define what REST should be, but you are out there building awesome products while the rest of the web world is still up in arms on what it has to be?
• agentultra 10y ago
  I think REST is a perfectly acceptable and well-adopted pattern. There's no lie to it. I think GraphQL could displace it but adoption will be key. What I am sick of with REST APIs is having to code them from scratch in dynamic languages each time and hook up all that laborious plumbing! I read in an O'Reilly book on the subject that good REST APIs are declared. To that end I've been looking to tools like PostgREST, PostGraphQL, Swagger, and the ill-named Servant. Define the data, declare the resource routes, and you're good to go; generate the server stubs, the client code, and the documentation from the specification. You don't get that from adopting a new standard every few years.
• abraae 10y ago
  This article is largely bollocks. 1) Almost every gripe in it refers to bad implementations, not bad specs. 2) It doesn't even mention HATEOAS. I'm no fan, but usually arguments about whether your API is REST or not revolve around how/whether you've done HATEOAS. 3) The rest of it is pulp tech writing that sounds like it was vomited out to meet some kind of publishing deadline. Case in point: > Consider, for example, when we might use the 200 OK response code. Should we use it to indicate the successful update of a record, or should we use 201 Created? Here's a clue - read the spec! (SPOILER ALERT: the word "Created" is the giveaway). To quote: 200 OK The request has succeeded. The information returned with the response is dependent on the method used in the request, for example: <snip> 201 Created The request has been fulfilled and resulted in a new resource being created.
  • mcguire 10y ago
    "2) It doesn't even mention HATEOAS. I'm no fan, but usually arguments about whether your API is REST or not revolve around how/whether you've done HATEOAS." You know that. I know that. But all the comments down to this point in the discussion have been over whether GET, PUT, POST, etc., are necessary or sufficient.
    • halostatue 10y ago
      …and having implemented HATEOAS in a service (via json+hal), we’re moving far away (GraphQL) because of versioning, payload weight, and lack of flexibility. I’m sure there are things we could have done better, but the reality is that our clients need things that work differently than a “proper” REST/HATEOAS service. We tried. We failed (insomuch as delivering a working service is failure, but we know it can’t grow the way we want it to grow because the payload weight is far too big). I’m not sure if it was us, or the fact that REST can’t map to everything we want it to be (it can’t, see the attempts to model actions performed to objects like IIRC fishworks did), but we are moving on.
      • icebraining 10y ago
        Like any other architectural model, REST is good for some things, not for others. Versioning and payload weight seem like weird problems to have, though. Seems like JSON might have been a poor encoding for your use case. By the way, do you have a link to that work by fishworks?
• Mandatum 10y ago
  I think the first comment/reply to the post hits the nail on the head, by Florian Klein[0]: > Awesome! You replaced REST with REST. How revolutionary: > Instead of transferring application state through the wire via one of its representations, > you know transfer its state through the wire via one of its representations. > Do I need to go any further? > I think so, because to me your confusion comes mainly from the vocabulary you seem to misinterpret. You didn't even talk about hypermedia or links! That's kinda strange in an article about REST. > Even tho I agree this vocabulary can be confusing, you should not throw the stone on the wrong subject (REST). > Your problem is HTTP, right? > Rest is not tied to http at all, and your point about making response bodies self contained is an honorable idea, but it doesn't change anything to your application being RESTful or not. I work building, debugging, deploying and integrating JSON-formatted RESTish web API's every day. I find purist API's to be the most painful to use, and I find people who take the this-is-pretty-much-RPC-over-HTTP approach to be the second most painful unless it's perfectly built for my use-case. There is a perfect middle-ground for most API implementations and really it comes down to the architects and software engineers implementing the API being able to think like API consumers and thinking of most use cases for their API's up front, then having a good level of "80% of people will use it this way, so we'll try and cater to the masses but support the other 20% like this". There are definitely the marketing types who sell REST as the be-all-end-all solution to APIs, and all the other bells and whistles that go along with it. That isn't unique to REST. I'm not on a mission to appease 100% of all use-cases for an API or integration. Such a solution will never exist and people trying to make out like there must be some sort of "holy grail" of API definition and design out there and %insert_current_fad% is wrong! No. We're doing our best, and today's API's with their API Test Consoles and their interactive walk-through's for people new to the API are a hell of a lot better than what we had before. [0] http://disq.us/p/103w6z6 http://disq.us/p/103w6z6
  • anentropic 10y ago
    What are the problems you tend to encounter with purist REST APIs?
• tobyjsullivan 10y ago
  On first pass, I totally agree with the author. I haven't reviewed the proposed alternative yet but fingers crossed. That said, I think he misses the single biggest issue with REST APIs that I continuously encounter and which has caused me to consider them sub-par. Representative "State" Transfer. REST APIs are only good for transferring around the state of stateful objects. However, CRUD operations are only part of the equation in most modern software. Much of what we do is performing actions on those stateful objects (or, better yet in the microservice world, avoid state altogether). REST provides no identifiable mechanism for performing actions outside of CRUD operations and is, therefore, a completely impractical solution. Most real companies' attempts to build a "RESTful" API just end up being RPC over HTTP dressed up to look like REST.
  • icebraining 10y ago
    REST provides no identifiable mechanism for performing actions outside of CRUD operations and is, therefore, a completely impractical solution. The mechanism is identifiable once you start to really think in REST terms. The problem is that people think in RPC, and so try to shove its model instead. REST is based on names (resources), not commands. Therefore, we must implement our actions as resources. Instead of having a "transfer()" command, you have a Transfer resource type, which you create to start one. Eg: POST /transfers ... (Body describes parameters) 201 Created, Location: /transfers/34 This change from a command to a resource additionally provides the benefits of REST, necessary for communication over an unreliable network: rather than keep your connection open while the action is processed, you get an URL you can poll to check if it is finished. This works even if the client goes offline for some time.
    • icebraining 10y ago
      To add to my previous post: it's not like this is a weird concept; every e-commerce site out there implements this. Imagine if we followed the RPC model: the user would click on "submit", and then the browser would wait for a reply when the order was finished being delivered - multiple days later! Obviously this is impractical, so people follow the natural REST model: they create an Order resource, then send you a link with which you can follow the status of that resource. But bring the "API" word and suddenly all of the preconceptions push developers to implement everything as function calls.
• mcguire 10y ago
  Mmmm. Multilayered multiplexing.[1] Yay. [1] http://128.232.0.20/teaching/0809/DigiCommI/tennenhouse1989layered.pdf http://128.232.0.20/teaching/0809/DigiCommI/tennenhouse1989l...
• madhadron 10y ago
  I've never actually seen a REST API in practice, just HTTP APIs, by which I mean I've never seen a fully hypertext driven interaction with data. Let me sketch what I would expect that to look like. I fetch from a URI (http://example.com/meep/boris http://example.com/meep/boris) and get back a response with Content-Type application/meep; version=3. My browser searches for a viewer for that content type. The content type defines the actions I can take on the content, either locally or talking to the server, just as it does for any other protocol passing data over the wire. That understanding has to be out of band for the model. But to be truly RESTful, the viewers must also be accessible via hypertext. For example, the response with the content could include a link header to point me to a usable default viewer for the content type. So you have to have a content type that whatever you're using (browser, SPA in the browser, etc.) knows how to interpret as a handler for content types. Whether it uses PUT, PATCH, or BABOON in HTTP verbs should be irrelevant. That's part of the protocol of the content type handler. It's that second part that's a problem. The security implications are a bit worrisome. And if you're shipping handlers only for your own data, you control all the pieces, so there's no point going through all the decoupling.
• robzhu 10y ago
  Like other posters have said, the author appears to be pointing out shortcomings with HTTP, not REST. Roy Fielding made it fairly clear that REST is not strictly associated with HTTP. REST, as an architectural style, is defined by a set of constraints: https://en.wikipedia.org/wiki/Representational_state_transfer#Architectural_constraints https://en.wikipedia.org/wiki/Representational_state_transfe.... Anything that meets these constraints is considered "REST". Most of the constraints sound like common sense for API design, and where most APIs are disqualified from being truly "REST" and merely "RESTish" is in trying (or not) to fulfill the Uniform Interface/HATEOAS constraint: that the client dynamically traverses information and operations from one resource to another via hypermedia links. Interestingly there's yet a deeper problem with fully RESTful APIs (Hypermedia APIs), where REST's Stateless Protocol constraint combined with HATEOAS creates an API where clients need to undergo multiple HTTP round trips to load the data they need. For example, suppose your app lets users browse movies. You might have a sequence like: client: "hey, I'm gonna act like a browser and hit api.com and take it from there" GET api.com => { "movies": { "rel": "content/movies", "href": "/movies" } } client: "hmm, ok I guess I'll click the movies link" GET api.com/movies => { "items": { "count": 4, "prev": null, "next": "/movies/page/2", [ {"href": "/movies/1"}, {"href": "/movies/2"}, {"href": "/movies/3"}, {"href": "/movies/4"}, ] } } client: "ok, I guess I'll fetch each of those movies (I kinda wish the server had just told me what those contents were in the first place)" GET api.com/movies/1... etc. => { "href": "/movies/1", "rel": "self", "title": "Waterworld", "image": "/images/waterworld.png", } ... And don't forget the client-side logic to join/order all this data and handle errors. This problem is called "underfetching" and it's present in true REST APIs by design. Ironically, many "RESTful" APIs break from the REST constraints specifically to avoid this problem. Another great article on REST APIs: https://martinfowler.com/articles/richardsonMaturityModel.html https://martinfowler.com/articles/richardsonMaturityModel.ht...
  • u801e 10y ago
    > Roy Fielding made it fairly clear that REST is not strictly associated with HTTP. REST, as an architectural style, is defined by a set of constraints: Out of curiosity, do you know of any examples of RESTful APIs that use a protocol other than HTTP (say like IMAP or NNTP)?
• eranation 10y ago
  Sorry for the controversial question, and I probably raised my eyebrow if I saw a candidate choose XML over JSON when taking on a recent project... but really, why JSON? No comments, no multiline, no schema. I understand that XML is bad because ____ (not cool, verbose, old school, only enterprises use it?) I am not a huge YAML fan but it seems this is the only human readable form of JSON. The lack of self describing human readable scheme is mind bugling. So SOAP and XSD is bad (?) so instead we got swagger (?) is it really better? Was ditching XML for JSON just due to cosmetic / trending reasons? We still use HTML for markup. Why did everyone ditch XML for JSON beyond just treading reasons is an interesting question.
  • paulddraper 10y ago
    JSON, as the name suggests, is easily and natively consumable by JavaScript, the only language to run natively in web browsers. And everyone uses a web browser. Ergo, if you develop an HTTP API, you should do it with JSON so it can work easily in web browsers.
    • eranation 10y ago
      Can you elaborate please? Browsers had native XMLHttp support before they had JSON support. The fact JSON (use to be) a subset of JavaScript and the browser runs JavaScript natively is not convincing. Other than evil eval(jsonString) (before JSON.parse was available) which is basically asking for XSS, what benefit you get from JSON being consumable by JavaScript? I think XMLHttp was available in browsers (in a vendor specific annoying way perhaps but still available) way before JSON.parse was available... am I missing something?
      • paulddraper 10y ago
        The XML in XMLHttpRequest is meaningless. eval() was present from day 1 and is the reason JSON looks like it does. Obviously it requires complete trust in the source (historically, the same origin).
  • kowdermeister 10y ago
• throwaway5752 10y ago
  What is it about CRUD over HTTP that drives some people nuts? A bit too much overhead, not perfect for high performance/low level data channels, and not perfectly standardized. But it piggybacks over a wildly popular level 7 protocol that takes care of security in a well tested way, already plays well with proxies/load balancers, has thousands of implementations in most languages, is well understood by network admins and usually already handled if you're shipping software to customers. It has a lot going for it. Sure - everybody ends up reimplementing async jobs and polling... some people prefer XML/json/edn/etc... some people get pedantic on 3xx and non-200 2xx status codes... differing standards on referencing other objects/collections/etc... some people use POST where they should use PUT (or insist upon using PATCH and OPTIONS). It has just as many faults. But it's wildly successful for are reason, and dismissing it probably is going to result in relearning a bunch of hard-earned lessons about integrating across lots of very heterogeneous systems and environments.
  • discreteevent 10y ago
    It's wildy successful for a reason, which is that its primary usee is by web browsers for document transfer. And as a result firewalls allow http over port 80 or https over 443. For a lot of cases you simply cannot communicate at all unless you use http. The reason for its success is that there is simply no other choice whether it's good or bad.
• snambi 10y ago
  Agree totally. REST is hard to work with and very confusing since every application does it differently. I have seen applications returning HTML response for errors cases. REST is better than SOA or CORBA, but we need something better.
• deathanatos 10y ago
  This article is a complete strawman. His description of a supposed "REST"ful API is the least RESTful API I've seen in a while: > The what-we-actually-indended-to-use request method embedded in the request payload, e.g. DELETE Don't do this. > The what-we-actually-indended-to-use response code embedded in the response payload, e.g. 206 Partial content. Don't do this! > If you’ve ever worked with a RESTful API, you know they are almost impossible to debug. You're begging the question. There exist plenty of APIs that abuse the HTTP methods and status codes, which I feel like is really the core argument being made. But completely ignoring it and what its purpose is is throwing the baby out with the bathwater. Read and understand the RFCs for HTTP, for a start; unfortunately, I'd wager that far too many devs of ostensibly RESTful APIs do not do this, and it shows when you get a response with a status code that makes zero sense. The vast majority of HTTP APIs I've interacted with violate both the semantic meaning of the methods and that of the status codes. (GitHub's is about the best I've ever seen.) A "RESTful HTTP API" is an API that uses the mechanisms in HTTP to accomplish the ideas of REST; (i.e., I'm not trying to equate HTTP and REST, I just think abuses of HTTP are a major impediment to understanding REST. Using HTTP well will naturally help you accomplish REST.) > can anyone out there explained to me what 417 Expectation failed really means? You've not read and understood the RFCs for HTTP. 417 Expectation Failed is obvious if you have; an expectation (on the request) failed (cannot be met by the server). An "expectation" is denoted on the request through use of the "Expect" header. The only existing expectation is 100-continue. Even if you do not know this by heart (and I don't expect that), it's readily findable: 1. Google "http rfc status codes"; unfortunately it's the second result; Google doesn't understand that the second result is an updated version of the first. Regardless, if you go for the first result, it points you to the second (-ish, b/c the RFC was split into multiple). 2. You select "417 Expectation Failed" in the Table of Contents. 3. You read the extremely straight-forward explanation. If you don't understand what the Expect header is for, the RFC links you to it. So what are the ideas of REST? Start at its (de-)acronym: "Representational state transfer". That is, transfer of a resource. A "resource" is just an "object" or a concept, a thing — the actual concrete thing represented by a resource is going to be determined by your domain specific problem. E.g., "a user's profile data", "a message in a thread", "a news article" are all "resources" in that they embody some concept or idea that we want to communicate the underlying state of. You also need a standard, or uniform method of uniquely identifying, or locating these resources, which is what a URL is for (you then see why it's lit. uniform resource locator). So we build URLs to stand in as names for resources. In order to transfer the state of a resource, embodied at a URL, you need to send it across a wire. You need to serialize it into some representation that's going to get transferred. That's what HTTP is supposed to help you do. If you were writing a RESTful API, embedding things like the status of the operation in the response body should feel wrong, because the status isn't conceptually a part of the resource you were trying to operate on in the first place; go back to our example of "a post in a thread" — whats a status got to do with that? While technically, yes, HTTP's entity body is capable of transferring arbitrary binary data, the end result of using it that way results in simply the re-invention of wheels, such as needing to signal the success or failure of operations on resources. HTTP's purpose, alongside the ideas of REST, is to pull out the common bits that occur when writing code that transfers representation of stuff around, such as, e.g., caching, getting an ok to transfer large content prior to writing it all out to the wire, knowing the status of the operation, or pagination of collections of resources. (I cannot count the number of times I've witnessed API designers reinvent pagination, badly!) The manner in which people like to use HTTP, with effectively only GET and POST (maybe!) is more akin to RPCs to me. It works. You can do that. But you then need to handle caching, pagination, status of operations, etc. on your own, and you'll end up, I believe, reinventing HTTP. Doing a lot of that (I think, and I think this was Roy's original point) is more effective if you structure your operations around transferring representations of resources around; this is especially visible in caching, because in caching you need the representation of a resource, because that's what a cache works with by its very nature. (As opposed to, say, making opaque method calls on a remote instance.) Go read [1]; nothing really in there is bound to HTTP, just that HTTP makes a lot of it easier. Also, while I understand that Roy has a lot of arguments around how representations should be hypertext — and I agree with them, mostly — I think that comes second to the ideas that: 1. A URL represents a resource 2. The point of GET / PUT / DELETE is to transfer the state of that resource. If you don't understand those two points, I don't think you'll understand the arguments behind hypertext. [1]: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... The other points, > They are easy to debug since transaction information is found in easy-to-read JSON inside the payloads using a single, domain specific vocabulary. Pushing everything into an opaque blob removes the ability for any tooling to pull out high level information. Chrome devtools, httpie, etc., all disprove this point. > Problem #1: There is little agreement on what a RESTful API is I agree. I also feel like too many people who think they know have not read anything from Roy Fielding, or even the HTTP RFCs. > The REST vocabulary is not fully supported depends mostly on > most client and server applications don’t support all verbs or response codes for the HTTP protocol. For example, most web browsers have limited support for PUT or DELETE. And many server applications often don’t properly support these methods either. This isn't true: JavaScript in all browsers in respectable use supports this; Android and iOS fully support HTTP; most server-side development languages have excellent tooling for this. This is a completely false statement, and requires proof, or at least a concrete example to back it up. (Were it true, it only invalidates the use of HTTP as an aid to accomplishing REST.) > Problem #3: The REST vocabulary is not rich enough for APIs POST is, essentially, a catch-all for odd operations not supported by other verbs. > Imagine we create an application where we want to send a “render complete” response back to an HTTP client If we have a resource that represents a rendering job, if you GET a representation of that render job, it can include some indication of completeness. The bigger problem here is actually HTTP's polling, IMO. Websockets might serve this specific example better, but this singular example doesn't invalidate that most web APIs boil down to CRUD $object of $type, which HTTP supports phenomenally well. > Problem #5: RESTful APIs are usually tied to HTTP Well, yes. At the end of the day, it has to be tied to something. HTTP is a pretty good something, with decent tooling. > They use only one response code to confirm proper receipt of a message - typically 200 OK for HTTP. Yes, you can send a single bit back. HTTP attempts to be a bit more rich than this. E.g., if something is in progress, and attempting to retrieve the data I just stored will fail until some serve-side job is complete, HTTP can easily signal this. Muxing them into 200 OK removes that information. > They completely separate the response content from the transmission mechanism. All errors, warnings, and data are placed in the JSON response payload. HTTP already has this: the response content is the body of the response. The transmission mechanism is HTTP. I don't want errors, warnings, etc., in the payload, where they are opaque and unusable by common tooling. > They can easily be moved or shared between transmission channels such as HTTP/S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH. These channels do not support transferring the state of something. (Okay, HTTP does.) telnet is a mostly dumb pipe, same for SSH. You would need to build some custom, non-iteroperable layer on top of that. HTTP is the standardized version of that.
• isuckatcoding 10y ago
  As the first comment in the article mentions, this guy just replaced REST with REST. Nothing revolutionary. I thought he was going to talk about some rpc mechanism or something.
• weq 10y ago
  As everyone else points out, GET and POST are really all thats implemented in anything else other then a catelogging system. So if we concede that people using these 2 operations are not implementing REST, what are they implementing? Well i would argue, CQRS. GET = Query, POST = Command Then our REST api becomes super simple and consistant across implementations. /api/run POST UpdateModelCommand { } /api/run GET ListModelQuery { }
• tflinton 10y ago
  fairly idiotic.
  • dang 10y ago
    Please don't post unsubstantive comments. If something is wrong, explain how so we can learn. Alternatively, if you don't have time to do that, please just don't post anything.
• kickingvegas 10y ago
  So much of my confusion is mapping POST and PUT to CREATE and UPDATE, which I've always felt was an arbitrary semantic decision. Why the unambiguous words CREATE and UPDATE are not used in the HTTP spec as method names is beyond me.
• Waterluvian 10y ago
  When I was given the task of defining how our multi-robot server would interface with our user interfaces, I eventually settled on REST. Most of what I knew about REST had been obtained that week. I implemented something pretty vanilla with Django and it all felt pretty elegant. I didn't have to worry about defining a protocol, there was pretty much already one for me: - GET, PUT, POST, DELETE (I learned there were others but were kind of niche/obsolete) - 200s for success, 400s for client (request) error, 500s for server error. It was all nice and worked great (and still does, years later). But over time numerous people started told me that no it's actually all wrong for one reason or another. I've heard that I should never use anything except GET and POST. That I should ALWAYS return a 200 and provide error metadata as a response if there actually was an error. That POST is actually meant for updates and PUT is meant for new entities. That the opposite is true. That neither is true and I should always use POST for any mutation of state. etc. I feel like I had success because I approached it from a position of ignorance, meaning I just implemented a simple, sane REST API and was none the wiser that I was doing it wrong.
  • masklinn 10y ago
    > I feel like I had success because I approached it from a position of ignorance, meaning I just implemented a simple, sane REST API and was none the wiser that I was doing it wrong. None of it is REST though, it's just one more RPC over HTTP protocol, which is also what TFAA advertises. Though your version uses HTTP as more than a trivial transport which I guess is nice.
    • Waterluvian 10y ago
      We read then manipulate the state of a multi-robot fleet by making HTTP GET, PUT, POST, DELETE calls that affect a database and robot broker/manager services. The state of the robots and the configuration of the system is represented in JSON. Interaction with the system is stateless, meaning you can jump in at any time, understand the full state of the system, and manipulate it safely. Interaction of a healthy system will involve numerous physical and virtual clients/servers, many of which are physically on the move most of the time. If this isn't REST then the Wikipedia page on REST needs updating or I'm just not explaining it well enough.
• imafish 10y ago
  > most client and server applications don’t support all verbs or response codes for the HTTP protocol. For example, most web browsers have limited support for PUT or DELETE. And many server applications often don’t properly support these methods either. I have never, as in ever, stumbled upon this problem. So I googled it. It turns out that what he means is that HTML forms don't support PUT and DELETE. In a world where everybody uses JavaScript anyway, I cannot see how this is a flaw in RESTful API's. It might be a flaw in HTML forms though.
  • abraae 10y ago
    To be fair, the verbs can feel a little weird. GET is easy. HEAD is easy. DELETE is easy. PATCH is easy, especially when you use one of the two more useful standards (RFC 7386: JSON Merge Patch, or RFC 6902: JSON Patch). PUT is not much use for large resources (like those typically found in business systems) since it requires you to provide every field, but usually you would want the back end to assign at the last the primary identifier, date created, etc. I seem to remember reading that even Roy felt PUT was not well designed. POST is a catch all for any other update/insert type activity. To paraphrase Winston Churchill, "http verbs are a poor system, but better than all the other systems that have been tried from time to time."
    • martin-adams 10y ago
      When you say you want the server to assign the identifier and additional fields, then I guess this would be considered read-only metadata against the resource. I don't recall seeing anything stating that in my RESTful travels.
      • abraae 10y ago
        Read-only or not, its still part of the resource, and so PUT must supply it. Here's a nice writeup: https://stormpath.com/blog/put-or-post https://stormpath.com/blog/put-or-post
  • kowdermeister 10y ago
    That was the point where his post turned into a TV-Shop style mockery :)
• cxromos 10y ago
  This is kinda SOAP in JSON.
• Animats 10y ago
  From the article: "The way forward: JSON-Pure APIs". I can see a little of this. It's better today to send parameters in HTTP data in JSON format rather than encoding them in the URL. If you're doing a pure GET, you can send parameters with the URL, but anything that changes server side state probably shouldn't be done that way. Of course, what's happening is that the JSON crowd is re-inventing SOAP, but, whatever.
  • masklinn 10y ago
    > Of course, what's happening is that the JSON crowd is re-inventing SOAP, but, whatever. SOAP uses schemas and the like, they just keep reinventing the same RPC as ever, except can't actually bring themselves to use the word. At least JSON-RPC is honest there, and ticks all of TFAA's box: * uses whatever's under as a trivial transport (covers 1, 3 and 6) * all data and metadata are part of the higher protocol (covers 2, 4 and 5) * is JSON (covers the entire essay)
    • sandythos 10y ago
      Hence also reinventing CORBA IIOP, DCE, Apollo NCS, Xerox Courier... Actual innovation in this area seems to be limited to JS background data sync libs. Ironically, reference-capable protocols like CORBA anticipated this whereas flattening it all REST-style was a step backwards.
• skrebbel 10y ago
  REST is successful for the same reason React Native is successful. Before REST, there was SOAP, similar in spirit to the JSON-Pure solution proposed by this author. SOAP's promise was a version of Java's "Write once, run everywhere". In the case of SOAP, this meant that if you have a SOAP client, you could consume data from any SOAP server with only the domain specific part different. Like Java, SOAP over-promised. In practice, there was horrible incompatibility between all the different SOAP providers and consumers; people lacked features so they hacked it on to the protocol, only to discover later that the default SOAP client in $THAT_OTHER_LANGUAGE didn't allow them to consume that hack as easily as it was in the first language. And so on, and so forth. REST, on the other side, hardly promises anything at all. In practice, most people doing a REST API agree on a rough idea of what URLs look like, and yes let's do our best and embrace HTTP verbs and status codes. In a way, REST is "learn once, use everywhere" - not unlike React Native's motto. This became wildly successful because the clients were all compatible from the start (after all, HTTP was widespread already). Compared the SOAP and most RPC setups, the clients are super underpowered; you need to do a bit of extra work. The only way to know what URLs to compose is to read the API docs (because HATEOAS is beautiful in theory only). The data is often JSON but maybe not, and you're again going to have to pay attention to the docs. In practice, though, it keeps the developer firmly in control. Most developers using REST actually understand the entire protocol. They know enough HTTP to be dangerous, they can look at what goes over the line and it makes sense. The moment you add more features to the protocol, you just make it more complicated and obtuse. I'm not convinced that's a way forward, not without serious (GraphQL-level) benefits.
• INTPenis 10y ago
  I've developed both REST and XMLRPC API's. The right tool for the right job. Sometimes REST is that tool. I also tend to combine JSON with REST. I still enjoy using proper HTTP codes when possible. So if you're sending a json payload to update an object that doesn't exist I'll give you 404. But at the same time you're able to create that object by defining its properties in a json payload in the next request and not some obscure url parameters or POST parameters. I don't see anything wrong with using proper HTTP methods and return codes when possible.
• staticelf 10y ago
  I think what this person is looking for is basically https://jsonapi.org https://jsonapi.org or similar.
• urbanxs 10y ago
  There is always that guys who takes a piss against the wind
• daliwali 10y ago
  I think this article is a big lie, because it's based on the premise that what is being described is in fact REST. First, it has nothing to do specifically with the mechanics of the HTTP protocol. There was an emergent pattern as people built APIs over HTTP, that they can re-use much of the semantics in common with HTML. HTML over HTTP naturally led to the definition of REST, where forms, semantics, and hyperlinks are not just an optional feature but a necessity. Formal specifications, meaning hypermedia API media types are just emerging, Hydra[1] and Micro API[2] to give examples. Fielding wrote about REST in 2000 and about a decade later was rediscovered by industry, and I hope that two decades later, people will rediscover its utility for APIs. My interpretation is that Fielding did not "invent" REST, but rather formally described emergent behavior on the web at large. Implementations may have differed wildly but had many features in common. The problems described in the article are the result of not following a media type suited for APIs. HTML is a wildly successful media type for machine-human interaction, there's no reason why there can't also be one or a few for machine-machine interaction. [1] http://www.markus-lanthaler.com/hydra/ http://www.markus-lanthaler.com/hydra/ [2] http://micro-api.org/ http://micro-api.org/
  • spangry 10y ago
    In complete agreement here, especially your description of Fielding's thesis. If you're looking to create an architecture that scales well and permits discoverability, then it makes a heck of a lot of sense to examine and formalise the properties of real-world architectures that have achieved this. More to the point, I think the original article's criticisms are pretty disingenuous. And his decision to ignore 'complicating factors' associated with network transport and caching: gee perhaps you're ignoring these because you CAN largely ignore these if you architect RESTful APIs. I mean c'mon, stuff like this makes me think the author is either very naive or very ignorant: The vocabulary of HTTP methods and response codes is too vague and incomplete to get agreement on meanings. No governing body - at least to my knowledge - has convened to set things straight. Yes, yes they have. Remember SOAP? That's an OASIS "standard", it's highly specified in detail and it meets the author's desire for 'content' being independent of the transmission channel (you know, for when you want to implement a web API over two tin cans and a piece of string). He should just use that, or the OASIS ratified SOAP v2 (i.e. ebms3/as4), which is also 'transport neutral'. Have fun with that. The rest of the criticisms basically boil down to "sometimes people don't implement it right" and "I don't understand HTTP response codes". There's really nothing that magical about REST. When you browse the web you are basically using a 'human-friendly' interface to a RESTful system. When APIs use the same architectural style it's the same thing, but for robots. That's pretty much it.
• jaequery 10y ago
  I think there are two types of developers. Pragmatic ones that puts focus on making things better/easier, and then those who generally don't give a shit, as long as they have some kind of standards to go by. Pragmatic ones are the ones who comes up with new frameworks, new languages, new standards. The rest are, sort of like sheeps. And we are all sheeps at some point. It's just a problem when the sheeps have a problem with someone trying and coming up with a new thing. So when I see a blog article like the author, I think we should just hear him out, get what you can get out of it and either support him or let him be. Sure, he may not be perfect but at least he has tried scratching an itch where he saw a potential problem and looked for a solution. And the problem he has is actually shared by thousands of developers so he is definitely not alone. Every couple years (hell, every couple months now), we face some new technology, or some new way of doing things and there is always the initial set of people who come across as being highly offended by it. Like back in the days when XML was all the hot stuff and when JSON came out, most bypassed it stating it's not sophisticated enough, doesn't have any xpath support, bla bla bla, doesn't have a reference book must be not ready for enterprise. It was the same thing with SOAP when REST first came about. And these type of patterns repeats throughout the years, from frameworks, languages, and probably everything else. People hate change. I think we all get that, it's just the way it is. However, over time the same people that were against it, slowly gives in to the same thing they were against the more people start talking or hears about it. I'm sure it happened to you at some point. So folks, don't just judge a book by it's covers. Give it some time and perhaps even give it a try. RESTful may be good as it is for you now, but I'm sure you also know that it is not as good as it gets. There are those who believes there are problems with the RESTful approach we have now and looks for a new standard that solves them. They may be right and perhaps will come out with something we will all be using some day. Who knows.
• jondubois 10y ago
  The author seems supportive of the core principles behind REST but arguing against its specific implementation in HTTP. I wrote a related article for Hacker Noon a few days ago which was trending on Reddit: https://hackernoon.com/rest-over-websockets-instead-of-http-81b0f0632295 https://hackernoon.com/rest-over-websockets-instead-of-http-... It's interesting that an increasing number of developers are pushing the notion of using REST-like ideas over WebSockets instead of HTTP.
• deleted 10y ago
  [deleted]
• blablabla123 10y ago
  I see the point that REST is not perfect, but better than "awful". IMHO it qualifies for pretty nice: Point 1: 200 is shorthand for 2xx. If I'm too lazy what the code is for "forbidden" or "insert something fancy here", I just return a 400. Does it's job and underlines that it's the user's fault. ;) Point 2: PUT and DELETE worked for me very well. I remember just one project where everything had to be "tunneled" through GET. Because "exotic" toolchain/frameworks, at least there was a canonical way to do so. Point 3: I think that's actually the nice thing about REST that its vocabulary is limited. Thinking about the pletora of unstructured HTTP XML RPCs and tons of structurally different Highlevel JS APIs for each vendor, REST seams quite relieving. Point 4: I don't really get that. Chrome Debug works awesome, I get all the information I need. There are many tools out there for mega comfortable debugging. Point 5: That's definitely a thing. I wish the article was only around that point.
  • ffjffsfr 10y ago
    > I see the point that REST is not perfect, but better than "awful". :+1 and they are also better than what author advocates. One thing in author proposal that absolutely puts me off is this: > JSON-Pure APIs (...) have only one response code to confirm proper receipt of a message - typically 200 OK for HTTP. This is terrible. PLEASE do not design your API-s like this, this will confuse the hell out of all bots, browsers and everyone who depend on status codes (and that's all web clients). Your 404 error pages will be cached and stored in google, redirects will not be remembered, error pages not retried, etc etc. I don't get the idea of json pure. Author claims that one benefit is: > All errors, warnings, and data are placed in the JSON response payload. But REST-ful API doesn't forbid you from returning informative error messages in json. Why not keep old HTTP semantics known by everyone and return json with informative error message? I also think that author confuses HTTP semantics as defined in actual WEB STANDARDS with purely academic work of Roy Fielding. Meaning of status codes or methods has nothing to do with REST-ful this is just plain HTTP semantics as defined by RFC-s.
• apo 10y ago
  > REST became popular when it was detailed and promoted by Roy Fielding as part of his doctoral dissertation entitled Architectural Styles and the Design of Network-based Software Architectures in the year 2000. Roy is well known for his contributions to development of the web, especially the HTTP specification. So far so good. > Roy advocated using the request methods he helped define in the HTTP standards to impart meaning to HTTP requests. Not even close. REST may be one of the most misunderstood ideas in all of computer science. As described in Fielding's dissertation, REST is a software architectural style whose main idea is that hypertext drives state changes, aka Hypermedia as the Engine of Application State (HATEOAS). Fielding leaves the transport protocol as an implementation detail. In other words, an automated agent (API consumer) should interact with an API in the same way that a human interacts with a Web site. User browses to well-known URL. Page displays content with links. User clicks on a link. And so on. A human doesn't need to read documentation on using any particular website any more than an automated agent should need to carry service-specific instructions on using an API. Media types and hyperlinks do all the heavy lifting. The stuff about structured URLs and response codes came later, was created by others, and has almost nothing to do with REST's central idea. It's a different architectural style altogether. From Fielding himself: > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
• sebringj 10y ago
  Relating to this...recently I needed to hook up a web app to a JSON RPC API and also extend that API, having to work with a legacy system. It was interesting to note that there was only one POST verb used in the entire API and the data format was always the same. At first I grumbled and was annoyed by the use of this system as it was old as hell but after some point, I was like, "oh, i don't have to worry about verbs now" or where to grab from params, query string, headers or body... so it was actually easier. I still hated it though because it wasn't REST because I was pretty biased with the status quo. What I'm trying to say is having more choices or more ways to do something isn't necessarily a good thing as it makes it easier for people to do it so many ways that they can screw it up or just make it weird for everyone else. REST is kind of weird that way and I agree with this article for the most part.
• lliamander 10y ago
  I think this article actually misses some good criticism of REST that I've encountered over the years: - how do you perform queries across resources? - how do you perform actions that don't map to CRUD actions (e.g. tell a server to reboot itself) - how do you perform actions that are transactional across resources? I'm not saying there aren't answers to these questions, but doing any of these things in REST is not straight-forward.
• FourierT-form 10y ago
  Isn't this just an argument for a JSON based SOAP API?