8 ms·
Most of this has little to do with REST at all, e.g. URLs don't actually matter in REST (because of HATEOAS) and should be considered opaque. This is more HTTP
by sjtgraham 12y ago
Most of this has little to do with REST at all, e.g. URLs don't actually matter in REST (because of HATEOAS) and should be considered opaque. This is more HTTP API best practises (best practise in the author's opinion). REST has become a meaningless term.
- eleumik 12y agoI agree. Links must be in the response, that's the point. Also I dont' understand this hierarchical path mania that brings one to make complicate things where URIs are parsed / produced. I use the query string for this in general, is much easier, only if I have some special needs I don't.
- jimktrains2 12y ago> This is more HTTP API best practises I'd disagree. If I were critiquing a non-REST API over HTTP, I wouldn't get upset about requiring a call to POST /processOrder at all, whereas I'd begin to convulse if they said it was a REST API.
- tom_b 12y agoYes. As a hacker who leans on books, blogs, and well-defined principles, RESTful api design resources have often been much more http RPC oriented. Hackers should pay attention to: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... I have also found collection+json and hypermedia application language (HAL) to be useful. Plus, I have spent a bunch of time reading the Restful Web APIs book from O'Reilly. Useful for me, as a relative newbie, in providing some logical foundation to start from . . .
- EdwardDiego 12y agoDo you have an example of an API that meet's Fielding's definition of REST?
- tom_b 12y agotl;dr: Not that I've dug into. I've found a number of people who point at the Github api as a good example of a RESTful api that includes hypermedia links for clients to follow rather than constructing URI requests manually. It looks good to me.
- jessaustin 12y agohttp://roy.gbiv.. http://roy.gbiv... Money quote: REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them. That’s fine with me as long as you don’t call the result a REST API.
- protonfish 12y agoI must disagree. REST is defined by four interface constraints: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... and identification of resources is the first principle. This functionality is implemented by URLs in HTTP and is therefore critical. HATEOAS (the 4th principle) also seems to be gravely misunderstood. It only means that the API should have a version that is fully useable in a web browser.
- sjtgraham 12y agoIncorrect. Resources are identified by URIs, but they are opaque, n.b. The Opacity Axiom "The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information." http://www.w3.org/DesignIssues/Axioms.html#opaque http://www.w3.org/DesignIssues/Axioms.html#opaque
- wahnfrieden 12y agoWhat the URLs look like is not a concern of REST though. Can you cite your latter point, since that's contrary to how I've seen HATEOAS explained? Many libraries do expose a browser-navigable form of the API, but I can't see how that's how it's originally defined nor it being a requirement.
- protonfish 12y agoAre you saying that it's just as good to have a URL be /fj3849-2qfjimpa as /customer? I agree that it is not strictly a REST principle, but in an API clarity matters. If we are talking about good practices, would your rather work with an REST API with readable, concise URLs or not? Maybe I am missing the point but the URL is one of the major building blocks of REST and choosing quality ones is a large part of API design. I stated that HATEOAS is widely misunderstood so it isn't surprising that there are conflicting descriptions out there. No matter what your interpretation, this principle is about hypermedia and application state and says nothing about what a URL should or should not be.
- jayvanguard 12y agoThis debate was settled almost a decade ago. URL forms don't matter in theoretical dissertation REST, but 15 years of practice has firmly decided they are indeed a core part of real-world REST. HTTP based web services existed before Roy's dissertation and while the formalizing of them helped them mature rapidly, the idealistic principles aren't the final word on the subject anymore. Real world practice now is.
- icebraining 12y agoURLs don't matter for 99% of actual REST usage. Your browser doesn't care if you're POSTing to /posts/new or to /jeskew. "APIs" are the exception.
- jayvanguard 12y agoAPIs are what we are talking about.
- icebraining 12y agoMy point is that APIs are an exception mostly because developers are conditioned by the RPC "APIs" mental models, which doesn't take effect when they're thinking about a "website" instead, not due to some fundamental technological difference.
- dragonwriter 12y agoThat's because the modern web itself is a REST API, whereas most of the things that call themselves "REST APIs" aren't.
- mcguire 12y agoAnd having extra irrelevancies to worry about such as "Version your API", "Use nouns, not verbs", singular versus plural, and nested resources are the consequences of being "practical".
- hawleyal 12y agoURIs matter and REST matters because people have been using them incorrectly for so long. Common mistakes like putting verbs in URIs instead of using HTTP methods. You are correct though, about the design of verbs don't matter (outside of conventions) as long as everything is done correctly.
- tptacek 12y agoJust off the top of my head: if you think of verbs exposed in URLs as a common REST mistake, you may not have fully absorbed the HATEOS concept. If you have HATEOS, you're unlikely to have verb URLs.
- k__ 12y agoany good resources to HATEOS?
- metaphorm 12y agowell, its just wikipedia, but its actually well written page on the concept, in my opinion http://en.wikipedia.org/wiki/HATEOAS http://en.wikipedia.org/wiki/HATEOAS key concept: > "The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in a service-oriented architecture (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL)." a truly RESTful service that follows the HATEOAS pattern doesn't require documentation to be hosted separately. it will supply all the information necessary directly through the RESTful service.
- k__ 12y agoHm okay. The key concept I understood but I don't get how clients and servers have to be, to just "get" each other in the way HATEOAS implies.
- metaphorm 12y agoyou're right, this is really about making a good JSON api that maps CRUD operations to HTTP verbs. REST is often used as a shorthand for that, though its not technically 100% accurate. that said, it was still a good article. I agree with the author on his best practices for JSON API design.
- ultramancool 12y ago> REST has become a meaningless term. Indeed, and this is why I think "RESTful" APIs are a huge problem - they're largely undefined. We have SOAP for defining these things formally without the need to worry about implementation differences. Unfortunately it was essentially abandoned because it was too complicated and excessive. It would be really interesting to see something SOAP-like with some more modern features and made a bit simpler.
- dllthomas 12y agoSimple Object Access Protocol was too complicated.
- ultramancool 12y agoUhm, I mentioned that in my post. Thanks for re-iterating? Personally, I thought it was pretty simple, but I come from a land of CORBA. I don't think the ultimate solution for "this structure is too complicated" should be "fuck structure altogether" though. Rather, we should try to arrive at a simpler structure.
- dllthomas 12y agoI wasn't criticizing your post. I was spelling out the name, because the tension between "Simple ..." and "... too complicated" amused me.
- 12y ago
- pbreit 12y agoThat is more of an indictment on how poorly REST has been presented. It remains mostly impossible to get a very good definition of REST or point to an API/whatever that is a good example of REST.
- serve_yay 12y agoI think that is at least in part because for a few years, every time someone thought they had a RESTful system, some genius would come through and declare it non-RESTful on account of not following some rule or other. So "RESTful" came to mean a type of HTTP API that tends to look a certain way. And so of course URLs matter. Saying something is "RESTful" is a surefire way to find out the ways in which it fails to match up with what some obscure document says.