I will bet money that most of these "RESTful" APIs are nothing of the sort. In almost all cases, when somebody says they're using REST, they're actually using ad-hoc XML-RPC -- fixed URLs, non-descriptive content, etc. Ignorant programmers have fixated on trivial aspects of some REST applications (use of PUT/DELETE, "pretty" URLs) and ignored all the important aspects.
This sort of thing happens a lot in software culture -- see people claiming Java or C# are object-oriented, that C++ is functional, that Python or LISP are "scripting languages". It's cargo-cult nomenclature, and it disrupts technical conversation to the point of uselessness.
Roy T. Fielding, who described the REST style, has an excellent blog post titled REST APIs must be hypertext-driven < http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... >, where he lays out some ground rules for calling any given interface a REST API.
I find Fielding's writing on REST opaque to the point of unintelligibility. This is a prime example. He actually has an example of a HTTP/XML interface he doesn't like... but he can't bring himself to talk in specifics, and instead hews to academic jargon.
So, can you translate his bullet points for me? Or can I safely assume that, yes, Roy Fielding doesn't believe these interfaces are "REST", but that I can safely ignore that fact and use the term "REST" the way the rest of the world does (RPC that uses URL patterns instead of WSDL).
> I find Fielding's writing on REST opaque to the point of unintelligibility.
I agree, somewhat, but I would formulate it a bit differently: REST is defined from a user's (or client's) standpoint. It is ill-defined on the other side, even to the point that it is hard to say whether any ruleset can be derived for implementers to use in building their applications. Essentially all of the popular conventions like Resource objects are somewhat misguided, as they are not in any way implied.
I have tried to hammer it in to my acquaintances and colleagues that if you pick one thing about REST to base everything on, it is links, not URLs.
I have pondered on writing a "everything you know about REST is wrong"-article, but have thus far been counterweighed by the consideration that perhaps this perversion that passes for REST is actually better than the real thing.
It's really simple: consider documents retrieved by requests to be nodes in a state machine, and consider hyperlinks in the documents to be directed edges to other nodes. That's it: your state is your position in the state machine, and your state transitions are navigation through the web of hyperlinks.
If you have an API which talks about URI patterns, for example, then it's not REST in this sense, because these URI patterns aren't found inside the documents as hyperlinks. Instead, they're found outside the document.
Similarly, if state is not encoded and transformed by following links in the web of documents, and instead is implicitly understood to be occurring whenever you do e.g. a PUT of some URI pattern, then hypermedia isn't the engine of application state.
A purist approach to REST, though, is IMO impractical for systems that aren't very like the web itself.
A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc.
A REST API should work over any protocol (HTTP, FTP, SSH, whatever) with enough basic functionality to support it. It shouldn't mandate any particular protocol.
------------
A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols
A REST API shouldn't require a customized version of the underlying protocol.
------------
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type
Here's big idea #1. Documentation for a correctly designed REST API will describe mostly what is being returned, not how to get it. Each resource is accessed via a different resource, except for the standalone root.
For example, you might start at the root resource http://foo.com/api/ . It returns, as content, a set of subresources that can be requested. The API documentation should describe what data the server sends for /api/ -- what format it's in (HTML, XML, JSON, etc), how to find its subresources (<a>, <form>, id'ed elements), and any relationship metadata it contains. The user agent (web browser) uses the MIME-type returned by the server to parse whatever it returns.
------------
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. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.
Big idea #2: the API documentation shouldn't just be a list of URLs; if it is, the server's URLs can't be modified without breaking clients. Clients should use hypertext to parse URLs retrieved from the server.
For example, the front page doesn't just give you a list of story IDs and require you to build the URL manually. It provides each URL in an anchor, as an opaque identifier, and your web browser simply passed it back to the server to get whatever it points to.
------------
A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names.
The client shouldn't have to contain a list of what URLs return what data. If http://foo.com/students/ returns a student list, either use the MIME-type (application/x-foo.com-students) or a standardized relation name (<foo.com><list rel="students">...).
For XML-based APIs, I would encourage the use of XML namespaces, although Fielding doesn't mention them. Sometimes you've got a few dozen different document types, and it just isn't worth figuring out MIME-types for them all; in that case, return (application/xml) and let the client use the namespace'd root element as an identifier.
------------
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience
This is mostly an elaboration of previous bullet points; clients shouldn't have to hardcode a list of resource locations. If your client has something like "students = Resource("/students/"), it's going to break when the server changes that URL.
"For example, you might start at the root resource http://foo.com/api/ . It returns, as content, a set of subresources that can be requested. The API documentation should describe what data the server sends for /api/ -- what format it's in (HTML, XML, JSON, etc), how to find its subresources (<a>, <form>, id'ed elements), and any relationship"
Why is this the biggest problem? For every protocol there are broken clients. For example, most XML parsers are broken. That is not a problem of XML, is it?
What's the alternative? For clients to refresh their copy of the "parent" resource [there may be a better term for this... I mean the resource used to access the resource that is to be gotten] often? For a commonly interactively accessed thing, it would introduce a lot of latency for clients to get it every time, so I suppose it must be cached... and then the cache of the parent resource be refreshed regularly and in case of failure? How far up the tree should that go?
In other words, if I want to get the Twitter feed for Joe's "ABC" group and I don't want to hardcode the URL for that resource, how often should I download (and cache), parse, and traverse the resources for Twitter's users then Joe's feed then Joe's ABC group, etc.? Or am I misunderstanding this?
A REST API should not be dependent on any single communication protocol...
URIs don't have to start with http, and they don't have to be locators. The rest of his bullet basically says that if you use a non-locator identifier like urn:..., then some other metadata or method will be needed to allow the client to locate the named resource. For example, you might have a resource that can map isbn numbers to online reviews of a book. You can pass in a urn:isbn:### identifier as part of the request url and you'll get back a resource with one or more URLs that point to reviews.
A REST API should not contain any changes to the communication protocols...
Here he's saying that you shouldn't make up new methods. A RESTful API doesn't just use uniform resource identifiers, it uses uniform methods as well. The exceptions are to fill in gaps in the standard methods (which presumably would be fixed in future versions of the protocol standard) and to fill in gaps in implementations (like browsers not supporting DELETE.) The former should be part of the core definition of your API, but the latter should be in an appendix that describes a temporary workaround. A common approach is to allow POST with a parameter named _method to workaround methods that browsers don't support.
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types....
Again, the methods are uniform and don't need to be described by the API. The media types and representations are resource-specific, so that's what the API documentation needs to focus on.
A REST API must not define fixed resource names or hierarchies...
Clients should never need to construct a url. Instead, every resource that the API can return should be reachable through a url that is embedded in another resource. All the client should need is the API's entry point. A classic example is a website: every page should be reachable through the home page by following links and submitting forms. You never need to go and edit the url directly to reach a given page.
Browsers and protocol standards are lacking in this respect, because they don't yet support templatized URLs. The workaround here is to provide a url template and some metadata that tells the client how to fill in the template, and if your client is a browser perhaps some javascript that fill in the template appropriately.
A REST API should never have “typed” resources that are significant to the client....
Unlike SOAP, which has typed data similar to a programming language (int, byte, string, boolean, etc) the only types in RESTful APIs are media types. The client is expected to know how to handle a media type in a useful and standardized way. This is related to the earlier point about the API documentation spending time defining the media types used by the API and how to interpret and use them (for non-standard media types.)
For those who want data types, text/json is a good media type choice because it uses the typical programming data types. But if you use JSON you're going to strongly couple clients to your service because you can't modify the json response without modifying the clients that parse the response. If you control both sides that's not a problem, but if you don't or you need to update both sides independently a less-coupled and more metadata-driven representation would be better.
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API)...
This bullet repeats what I mentioned above about clients not constructing URIs.
I think you're wrong to dismiss most developers' efforts at a REST API as cargo-culting. A half-ass REST API is better than XML-RPC or SOAP, at least in my humble opinion.
Out of curiosity, though, do you know of any examples of what you consider "true" REST APIs vs. examples of "ad-hoc XML-RPC masquerading as REST" APIs? Maybe I don't have enough experience consuming true REST APIs to be able to fully appreciate their merits.
The prototypical example of a REST API is a web application. They use a standard content type (HTML or XHTML), hypertext to link resources, and typically don't require any out-of-band technical information to work.
Right, that makes sense. But I guess I don't really understand how that moves the conversation forward.
Maybe I misread your original comment, but it sounded to me like you were claiming that there are a whole buncha crappy REST APIs out there that are no better than the crappy XML-RPC/SOAP APIs of yore, and that there would be a whole new world of coolness if only they stayed true to the REST protocol.
Saying, "oh, it's just the web," is just another variation of the obscurity in Fielding's post that tptacek is complaining about in his comment.
Anyhow, it's not like you have some responsibility to justify REST to me or anything, but I'm as yet unconvinced of what this gap between "true" and "pretend" REST APIs really is, and what benefits lie for everyone in close that gap.
EDIT: Just saw your "translation" of that Fielding post in reply to tptacek's comment, which was quite helpful.
I'm not claiming that XML-RPC or SOAP is "crappy"; there might be poorly-designed implementations (and of REST also!), but both have vital and important use cases. I have never used SOAP, but have both designed and consumed many XML-RPC APIs, and have no problem with them.
It's very important to use accurate terminology when discussing software and technology. The statement "Foo.com uses a REST API" only contains useful information if 'REST' is meaningfully defined. If 'REST' is redefined as a synonym for 'XML-RPC', then we lose the ability to distinguish between a REST and XML-RPC API in written or spoken conversation. I am not making any value judgment regarding either API style; they are simply different, and should be kept distinct for the purposes of communication.
> Ignorant programmers have fixated on trivial aspects of some REST applications […] "pretty" URLs
Hell, legible urls isn't even remotely part of REST, it's completely unrelated, it's absolutely possible to have a RESTful API with entirely unreadable URLs.
The problem is that he leaves so much underspecified.
This may be a reaction to the extremes of WSDL and SOAP, but how could the current outcomes and state of "REST" APIs be any different, if no one person can agree particularly much on what a REST architecture is?
The story is very much the opposite in enterprise apps; I can't remember the last REST interface I saw, but we see SOAP interfaces every week, in new apps.
Unfortunately, SOAP isn't going anywhere. It's just not popular with Internet startups. Neither is ASP.NET.
The problem is that the interconnected web of services are emphatically REST. This is the next generation of enterprise systems and it is growing quickly. One you adopt salesforce.com as your CRM strategy the next thing you want to do is integrate that system of record into the larger enterprise system. While Salesforce.com does offer SOAP services they in the end had to offer REST based services due to overwhelming demand and while they support both my observation is the the REST services are getting more attention (I don't work for or represent Salseforce.com, so take that statement for what it is worth, an opinion). If demand drops off it makes logical sense that the SOAP services will be deprecated. Further there are some SaaS systems that do not offer SOAP at all and that number is growing daily.
The enterprise of the future looks like an ESB that brokers data to and fro an assortment of SaaS, with some core in-house systems in the mix. It makes sense for companies whose bread and butter is not technology and places economies of scale on the SaaS providers. Many of those SaaS are opting for REST only implementations.
In a way it makes sense, for alot of the integrations you are wanting to pull data from the system for analytics, trending and reporting along side an aggregate of other data sources. REST make sense because it (loosely) acts like SQL which despite it's problems is a good data manipulating language.
The thing about REST is that someone needs to come up with a uniform and simple authentication and authorization mechanism that is seamless across the board.
The thing about REST is that executing on it involves understanding REST. The thing about SOAP is that you can practically push a button in your IDE and get a SOAP interface. No, the enterprise world is not about to transition to REST.
It's one button away... as long as you have the same technology on both sides (and then, why are you incurring all this overhead anyway?) Maybe this has changed in the last 3 or 4 years, but the last time I tried to get .Net and Java stacks talking via SOAP was a royal pain.
Boy, you said it. I tried to upvote, but I guess commenting kills my upvote.
Fing "Enterprise". Beam me up Scotty, there's no intelligent life here.
IBM and Microsoft drop the SOAP, and we get stuck picking it up. I hate* implementing SOAP clients for random SOAP server implementation of the day..
I'm sorry, Rob will be back shortly. We apologize for the outburst :-)
...
Boy, you NAILED it exactly, though.
REST sure seems simpler: define the document/content types, or schema, and just use links to GET things. Save POST for the few things that actually change state, then document carefully how the content is to be sent back up.
It turns out a good deal of services really are READ-ONLY anyway.
Making the simple things simple: give me my damn document! Let's keep it encrypted, and I'll prove I'm authorized to see it:
> It's one button away... as long as you have the same technology on both sides (and then, why are you incurring all this overhead anyway?)
If you want to make it look like you have an open API, while only having to do enough work to expose the way your two predefined systems already communicate, SOAP is the answer.
I'm part of a 7 figure project right now. We're a .Net shop, they have a Java infrastructure (and are as "enterprise" and process-laden as you can imagine and then some). We need to integrate -> See, we're right there.
SOAP it is for us and I do have to say that I'm rather relaxed. For us it's just one way (Java services, Java generated WSDL, we just consume/use the stuff), but it works rather well.
Unless you don't know about 3.5/WCF/Service References and try to do it the old-fashioned "Web Reference" ASP.Net way: That's a royal pain and just plain doesn't work at all for some (valid) SOAP things (some sequences of alternating complex types a la [Key, Value, Key, Value,...] for example cannot be mapped). Guess how I found out..
While I agree SOAP will remain dominant in the enterprise space, so is Java. And there are Java frameworks out there like Restlet that make publishing RESTful APIs nearly as easy as SOAP for those in this environment.
The thing about SOAP is that you can practically push a button in your IDE and get a SOAP
Sure, I am not supporting or detracting from SOAP, just highlighting the trending I am seeing in the SaaS space and I used Salesforce as an example because it is one that has made huge inroads into the enterprise space. It is the champion that got business executives looking at the advantages of SaaS. It is a logical conclusion that Accounting, HR, etc. will be adopted by the enterprise once someone mixes the formular right for SaaS in those spaces.
REST means a bit more than just "everything has an HTTP endpoint"; it means everything has HTTP endpoints that behave in approximately the same way, using approximately the same conventions.
Also, the term REST is usually used by people who don't know what the hell it actually means. For instance, people say that Twitter, Amazon, Ebay, just about everybody have "REST APIs" but they really have "POX" (Plain Old XML) or "POJ" (Plain Old Json) APIs.
I've had both good and bad experiences with SOAP. I remember wasting a few days figuring out how to get a PHP app to authenticate against an ASP.NET SOAP implementation... I did get the auth to work, but then I ran into other problems, and we found these bozos had a competitor that had a simple POX api that took five minutes to get working.
On the other hand, there was the day I pointed Visual Studio at the WSDL file for the Salesforce.com API and was quite astonished to see it build all the stubs for a very complex API with just the click of a mouse and no hitches at all.
I'm not worried about the people who think REST = !SOAP.
I'm worried about the people who think they understand REST, build systems, and discover too late that they've got to rebuild their whole communication protocol because performance and reliability are just a disaster.
So it's not just an academic debate, it's about the difference between systems that work and systems that don't.
And how do you define whether something is "HTTP-based" or not? Because using HTTP is not quite a good enough condition: SOAP can use HTTP as a transport, and XML-RPC has always done that (I'm not sure it allows any other transport).
The debate still exists, it's just moved. You're still going to have people calling anything with HTTP in it REST-ish just because it's another nice acronym to pad their resume.
I once tried to get REST apis adopted in an enterprise setting (as part of a tiny Ruby team). Talking to people in Java and .NET teams soon revealed why there was outright hostility to REST apis:
- lack of knowledge about REST
- poor support (if any) for REST apis compared to SOAP in the vendor tools.
Of course, getting .NET and Java services and clients interoperating with each other using SOAP was always problematic - but the teams I spoke with tended to work within pretty vertical technology stacks and services. So it was Java clients talking to Java services, or .NET clients talking to .NET services. So they saw SOAP as a good, familiar solution.
> The story is very much the opposite in enterprise apps; I can't remember the last REST interface I saw, but we see SOAP interfaces every week, in new apps.
That's kind of like saying "I can't remember the last hybrid car I saw here in Cuba."
The enterprise I am affiliated with (the kind that can build its own annihilation-focused moonlike space vehicle) is already using and/or moving to REST interfaces internally and externally.
I have to deal with SOAP APIs at work (Google, I'm looking at you) and they are seriously the bane of my existence. SOAP and the people behind it need to die a slow, painful and lonely death.
Can you explain why? I mean, sure SOAP has its problems, but is anything else really that much better?
You move the action and some parameters into the request itself. You change the representation from xml to json. You get rid of schemas and namespaces (which makes the service either better or worse, depending on its size). People seem to be very upset about SOAP wishing it death. What is it that you're actually complaining about?
It's complicated, difficult to understand, requires large tools (expensive ide's) to be productive with, different vendors have different interpretations of SOAP anyways.
Basically, it's a bunch of extra work and requires more documentation due to the complexity of it's implementations.
Also, SOAP libraries (e.g. Soap4r) are problematic (doesn't talk to Micro$soft's version of SOAP properly).
REST is over HTTP. Just about all programming environments have a HTTP library.
I've never had to use SOAP so I may be off here but isn't the above "just" a matter of bad implementations and not necessarily SOAP itself ? It sounds like blaming HTML/CSS/Javascript because there are crappy browsers that don't follow the standards.
I think a lot of it comes down to SOAP, and related standards, being ambiguous and changing enough over time that even if you follow the standards, it isn't necessarily clear what you can and should do.
Take a look at WS-I, the standard which tells you just how you should implement all of the standards that came before it, if you actually want to talk to other implementations: http://ws-i.org/profiles/BasicProfile-1.2-WGD.html
Just playing a devil's advocate here a little bit, but soap doesn't really require that much. For example for .net, you just run wsdl on some url and it generates the interface code for you.
Also the complexity is needed when your size goes up. Even verifying that the requests make sense is easier with schemas. Right now there is some project for json-schema going on, but it's not crazy popular yet. SOAP can be self-documenting too with its own structure mappings, type restrictions, etc. etc.
Don't you think it's only delaying the fact you'll have to reimplement the same stuff at some point yourself (since json based rest simply doesn't provide them out of the box)? (yeah - I know rest is protocol independent, so you can have xml and schemas too, but majority of "rest" services just throw some json and hope it sticks ;) - too bad if it changes between versions)
First of all, the fact that you need such a code generator for the interface is a smell, not a good thing. To consume a REST service, you just need an HTTP client, possibly some authentication hashing, a url, and parameters and a json parser. You then get a hash.
The Web services I've used tend not to be super complicated. A handful of api calls tend to be used.
There's also versioning, which is handled well with a good url structure.
Also, the schema problem is more of a JSON vs XML issue. I personally use JSON because it's simpler for flatter data graphs. I also use JSON schema btw. XML does have the advantage of xpath (or css selectors) too.
But even in the REST + XML case, the XML is simpler than the XML + SOAP case.
Which brings up Content-Type. Rest can serve pretty much any content type in a way that's readable by almost any web-enabled client. Not so with SOAP. You need to have more software.
Basically, I can add these features on an as needed basis. REST is easier to work with right now and I probably will not need all of the features of SOAP. That's the gist of why it's less popular now.
Rails apps make RESTful services fairly easy, even if it doesn't usually cover the entire spectrum of RESTful actions. Many Rails (CRUD) controllers are going to have 4 RESTful actions built into that one controller/service, so a single app might have one RESTful service for each model (assuming it is exposed).
SOAP has been overtaken for sure, but I think that first pie chart set should show the number of services, not just the percentage. My guess is that the number of SOAP services may have grown, but the number of RESTful services just grew much more quickly.
Unless you're using a framework like .NET where everything is done for you, SOAP is just too much trouble and complexity for simply data exchange. Especially if you're trying to consume it from Javascript or Flash.
I'm not sure how much of the "REST" in the pie chart is true REST, but POX and POJ is so much simpler and easier for cases where you don't need a full blown strongly-typed web services interface.
SOAP has 50x the features of REST. Even most REST advocates will accept that there are scenarios, where it's better to use SOAP. If you need complex security, reliability, addressing, etc. why not let Microsoft/IBM/Oracle do the dirty work?
RMM (Richardson Maturity Model) provides a good set of criteria for evaluating adherence of a web service to the Representational State Transfer Architectural Style.
i get the feeling that an important concern that prevents soap adoption is the bulkiness of the xml standard that it's based on. i hope that the efficient xml interchange standard will make that concern go away that.
solutions like thrift seem to reinvent most of what's been done with xml schemas and other standards around soap solely on the grounds of performance.
oh and it's surprising that json-rpc is not in this pie-chart. pure rest is not powerful enough to communicate a complex object structure.
the way i see it exi is to reduce the time to parse xml. but i'm not terribly familiar with exi standard (draft) and would like to know what's so terribly wrong with it.
This sort of thing happens a lot in software culture -- see people claiming Java or C# are object-oriented, that C++ is functional, that Python or LISP are "scripting languages". It's cargo-cult nomenclature, and it disrupts technical conversation to the point of uselessness.
Roy T. Fielding, who described the REST style, has an excellent blog post titled REST APIs must be hypertext-driven < http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... >, where he lays out some ground rules for calling any given interface a REST API.