I like how Dropbox bucked the trend and went with a simple POST based API. JSON parameters in. JSON response out. No complicated urls, strange headers, verbs, hateoas, etc..
https://www.dropbox.com/developers/documentation/http/docume...
I like how Dropbox bucked the trend and went with a simple POST based API. JSON parameters in. JSON response out. No complicated urls, strange headers, verbs, hateoas, etc..
https://www.dropbox.com/developers/documentation/http/docume...
State is carried by the client, the client traverses links to find out what it can do, the responses are described by a published content type, and the content type defines the semantics of the protocol.
It's not hard, but people like to pretend that it is. Nothing says you can't stick to GET and POST, nothing requires weird headers.
"ReST in Practice" is a great introduction for engineers.
Facebook, Amazon, and Hacker News are good examples of RESTful applications. You can enter them through their website roots with no prior knowledge beyond standard web media types like HTML/CSS. The site roots display some information, expose some functionality like search, and link to pages with more capabilities like to create an account. The search function is expressed as an HTML form, and when the user submits their search, the HTML spec tells the browser to navigate to a new URL composed from the search form fields. The search result page displays a list of hyperlinks to other resources, such as products on Amazon or people on Facebook. Navigating to those pages lets you discover information and hyperlinks to other resources such as a person's photos, related products, etc.
The way a browser navigates through a website by following links is the classic example of a RESTful application, and is the meaning of "hypermedia as the engine of application state". Fielding also wrote a blog post clarifying REST and its constraints: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
> A REST API should be entered with no prior knowledge beyond the initial URI and set of standardized media types that are appropriate for the intended audience. A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). A REST API should never have “typed” resources that are significant to the client. 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
Some confusion about REST seems to stem from misguided attempts to apply REST to scenarios for which it's not a good fit - scenarios where there is by necessity tight coupling in the form of mutual knowledge of specific data types and operations. Other confusion about the term "REST" comes from applying subset of its principles, resulting in a popular label that refers to a large spectrum of architectural styles. The Richardson Maturity Model helps organize these functionality subsets into levels that can be named and considered separately - services termed REST are sometimes level 1 or 2 in the Richardson model.
http://martinfowler.com/articles/richardsonMaturityModel.htm...
An API is probably the worst thing to try to make truly RESTful, in the full HATEOAS sense.
Further confusion comes from the fact that some of the REST constraints are actually very useful in machine-to-machine API design. Thinking about a system in terms of a large number of resources operated on by a standard set of verbs is nice. Caching is nice. The un-bloating of HTTP bodies from the SOAP days is nice.
I think there is some consensus that we can call that thing an "HTTP API" rather than a "REST API", which might start to clear up some of the confusion.
With the web, it is not the browser doing the navigation; It is very advanced AI wetware.
It is hard to find widespread examples of machine to machine interaction based purely on RESTful discovery.
I think REST is interesting - but at the end of the day, is it really all that different from other communication mechanisms?
Why does it drive you nuts?
REST as a concept was created as a way of characterizing a successful architectural style seen in web applications, a common set of constraints and advantages realized from those constraints. REST is attempting to characterize the architecture of the web, so I think it would be accurate to say "the web itself is RESTful":
> The first three chapters of this dissertation define a framework for understanding software architecture via architectural styles, revealing how styles can be used to guide the architectural design of network-based application software. Common architectural styles are surveyed and classified according to the architectural properties they induce when applied to an architecture for network-based hypermedia. This classification is used to identify a set of architectural constraints that could be used to improve the architecture of the early World Wide Web.
> Architecting the Web requires an understanding of its requirements, as we shall discuss in Chapter 4. The Web is intended to be an Internet-scale distributed hypermedia system, which means considerably more than just geographical dispersion. The Internet is about interconnecting information networks across organizational boundaries. Suppliers of information services must be able to cope with the demands of anarchic scalability and the independent deployment of software components. Distributed hypermedia provides a uniform means of accessing services through the embedding of action controls within the presentation of information retrieved from remote sites. An architecture for the Web must therefore be designed with the context of communicating large-grain data objects across high-latency networks and multiple trust boundaries.
> Chapter 5 introduces and elaborates the Representational State Transfer (REST) architectural style for distributed hypermedia systems. REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems. [...]
> Over the past six years, the REST architectural style has been used to guide the design and development of the architecture for the modern Web, as presented in Chapter 6. This work was done in conjunction with my authoring of the Internet standards for the Hypertext Transfer Protocol (HTTP) and Uniform Resource Identifiers (URI), the two specifications that define the generic interface used by all component interactions on the Web.
(To be clear, I'm not intending to comment on whether REST is good or bad, nor its suitability to a purpose like API design. I just mean to comment on what it factually is and is intended to be, since from my perspective it frequently seems to be misunderstood.)
[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/introduc...
Fielding's REST requires that the protocol be "stateless"... not that there be no state, but that the client and the server need not keep track of each other. Cookies, as Fielding explicitly calls out, are in violation of this principle. Every website that uses cookies is not RESTful.
Some people might conclude from this that FB, Amazon, and HN are "not good", because they're not RESTful. I personally conclude something else, but YMMV.
Also deciding to put the session ID in a cookie not the URL is purely a pragmatic approach (e.g for security reasons).
It's still possible to use sessions and other ways of maintaining client state while adhering to other stateless principles such as indempotency of certains types of requests.
I've built hypertext APIs, and they worked really well.
We had a(n overly) complex domain model where most of the complexity was around managing a permissions model for access to resources. We tried a whole bunch of ways to represent the actions available to end users, but the only one that worked really well was to advertise a URI when you could do something, and to omit it when you couldn't.
All the nightmarish logic was safely hidden behind the uniform interface. Clients only needed to know that they should follow links, and that the absence of a link meant that a resource wasn't available to them because reasons. It was a beautifully natural mapping of a difficult problem domain into a simple consumption model.
As a bonus, we could change URI structures around when we felt like it, and our clients never missed a beat, because they always followed links from a well-known entry point.
It's not always the right choice, there is plenty of room for simple RPC, but for workflows, and dynamic discovery of resources ReST works a treat.
And haven't this people been right? :)
It was (and still is, but people are fortunately more skeptic) completely oversold like REST now.
Imagine if Dropbox registered a set of mime-types for each of the different resource representations. Those mime-type RFCs would describe how clients interpret the representations whilst simutainiously giving Dropbox the ability to change the server as they need without fear of breaking clients.
This would be because clients would be foxing on how to process the media-types, not the API. The various interactions a client can make with a representation (regardless of the URL it came from) would be bound to the media-type e.g. rel-types for edit, upload, create etc which the RFC would describe the appropriate HTTP interactions e.g. POST a media-type of x to the url at rel-type "edit".
However, I think the real reason that REST hasn't been adopted fully is that service providers like Dropbox have found that there advantages to binding client developers to their hardcoded APIs; the last thing Dropbox wants (and what REST would provide) is a standardised set of media-types and RFCs describing the interactions for a standardised way of interacting with an external cloud-based storage provider.
It's just another form of lock-in, and reminded the cynic in me of the bad old days of MS Office document lock-in.
When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities. REST or not building a client for one doesn't really make you closer to using another. Also Dropbox's old API was REST and it doesn't seem more portable (https://www.dropbox.com/developers-v1/core/docs)
The way a client interacts with the server is via the media-type and HATEOAS (via the rel-types).
If Dropbox's API was RESTful, you'd be able to use Google by only switching the initial URL - which could even be configurable by the user, or auto-discovered from the website.
When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities.
They don't vary _widely_ in concepts and capabilities, they add a layer on top of the same concepts (files, directories, upload/download, get public URL), and REST allows you to support generic and specific clients easily, by either using extensible or multiple media types.
Also Dropbox's old API was REST and it doesn't seem more portable
It resembled REST, but it wasn't. A good way to tell: if you need a documentation page with a list of all the URLs you can call, it's probably not RESTful.
You really don't think that a flexible client which is able to discover resources and actions based only on an initial URL is more complex than one which is more hardcoded to a specific implementation and resources? I must be missing something, because to me, it obviously is.
The obvious example of the Web and web browsers is not entirely convincing to me. Yes, browsers are flexible, but at the same time, the Web is an incredibly specific example. There are "hardcoded" expectations of what a web browser must be able to do, that I simply don't see in more general examples and use cases. And whenever we want to do something out of the ordinary with a web browser (I know, I know, "web browsers were never meant for that!") this general model of the web breaks down and we stray into wildly incompatible and hacky ways of doing things.
When the conditions are right, you do see this: RSS/Atom is a good example.
Show me a general purpose program that can navigate, interpret and comprehend a variety of media types and I will show you an AI.
But what I really see as the main advantage is the decoupling of server and UI, kind of like Android Intents on steroids. By using standard formats and dynamic routes between them, the user is no longer tied to a silo with a window through which they can interact with their data; they can know use his own chosen software to handle the different types of information, jumping through them as needed, without ever being locked-in to a particular provider.
And for the developers, why are we building the same crap again and again using the API du-jure, when 90% of it uses the same concepts as existing software? Why do we need thousands of libraries and middleware that provides a "single API to many services"? We spend so much effort building these rickety integrations, just because the providers insist on using different names for the same things.
Doesn't it abhor you, the waste of it all?
I agree that the current situation is crappy. I agree that HATEOAS/REST ideas implemented properly and with the intend to cooperate would help a lot, and that there are many worse candidates for a standard.
I disagree that HATEOAS/REST would matter that much, compared to the "implemented properly and with the intend to cooperate".
Also the existence of WebDAV doesn't really demonstrate that merely adhering to REST will make your clients portable.
It's been a while since I've worked with it, but IIRC, WebDAV is one example.
> Dropbox's old API was REST
That's not REST. It's that weird anti-REST where people define URI patterns instead of media types. I don't know why it became trendy to label things like that REST, but they aren't.
WebDAV? You can get pretty far with eg davfs and Plone/Zope -- and you can also mix and match servers and clients. Now, lots of WebDAV clients and servers are broken in many sad ways... but it exists.
Fielding worked at Day Software, which made a web content management system. They contributed parts of their system to the community as Apache Jackrabbit [1] before getting acquired by Adobe.
Not sure if Day Software's APIs match your asks though.
I'd argue it's not a problem if a vendor can generate clients for his API.
I'd also argue that most clients break with each API version anyway, because of the way developers code them.
As I remember REST was popularized by Rails a few years back. If you go back and look at the railsconf talk by Hansson in 2006 you can see that the Rails people just wanted something that handled CRUD operations. However, one of the drivers behind REST was to provide web services for machine to machine communication - something that was traditionally done by WSDL files in SOAP. The Rails people didn't really have much of a need for HATEOAS, because they were not interested in replacing WSDL files. Primarily they wanted to get away from the 800 pound gorilla that was SOAP services (that back in 2005 was what every Enterprise Java web app was doing). As a result the focus was primarily on PUT/GET/POST/DELETE.
I've seen a lot of "REST" API's that are actually HTTP/RPC API's or quasi-REST API's that mix REST for simple things, but then begin exposing RPC calls as the developers ability to manage complexity breaks down. I've never seen anyone actually using HATEOAS yet (maybe i've been isolated??)
Usually when your boss says "And it has to have a REST API!!" That means that 1. It must use the internet, 2. It must return JSON, 3. It uses URLs to do things. Basically if the above is true it's a RESTful API. I think that most developers actually believe that are making a REST API even when they are not - simply because they don't really know.
Your right about being the new XML buzzword though. 10 years ago if you did web services having WSDL, XSTL, SOAP and XML on a resume meant you were the shiz. Today you have REST and AngularJS on your resume if you do web development. Meh :0
Github AFAIK
There are people who understand it to varying degrees. Some who completely understand it and some who don't understand it at all.
So no, it's not a buzzword, it's just a concept.
PS. Dropbox's API requires a lot of hardcoding because of that very switch. Hardcoding that HATEOAS lets you avoid.
Because it is not a well defined protocol, you cannot use the same client library to access random REST APIs. You use/write one library to access Twitter's REST and another to access Facebook's REST. You could argue that you use HTTP in both cases, but that's just the underlying transport protocol - not the API "language" itself. Because of that fact I blame REST for the millions of developers hours wasted in re-implementations of hundreds and thousands versions of the same "concept".
The REST "idea" sure looks sexy when you put it next to an atrocity like SOAP, but that's one of its very few merits.
You misunderstand what REST is. It's not a protocol, it's an architectural style. Of course you can't build one client library to access arbitrary REST APIs – that's like complaining that you can't build an object-oriented library that can be used by any object-oriented language.
REST does, in fact, have a precise definition that is possible to understand and agree on. It's here:
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
I think REST is quite clearly a buzzword. That doesn't mean it's not also a well defined concept; just that it's fashionable to use the term even when that concept doesn't apply very well.
I've had the "pleasure" of working with big European consortiums where REST is very much a buzzword. I quickly realized that people were using the term as a synonym for "HTTP" for the purpose of making grant proposals and deliverable reports sexier. It's definitely a buzzword!
In my experience hiding the existence of a network behind several layers of abstraction is a really bad idea.
REST APIs are nice because they follow the data model so closely but there are so many cases in which I am trying to overload something to bend the pattern to my needs. Then again, Stripe seems to have created a fantastic API that handles many complicated cases so maybe it just requires more upfront thought - https://stripe.com/docs/api.
I disagree that REST is a buzzword, though. I think that REST has become so popular because it's a very effective way to construct an API.
afterthought: There are plenty of "RESTful" APIs that miss the mark on important concepts in the pattern. In this case, I would say - yes REST is worthy of the term buzzword.
But at the end of the day, Dropbox is probably going to be just fine with their RPC API. So what gives? Why should Dropbox care about REST? How would you sell the CEO on it?
I'd love to read a follow up blog post called "What does REST buy you anyway". Related: https://xkcd.com/1270/