Is it possible to consume a hateoas type of restful webservice via (a) javascript (framework - e.g. angularjs)? I imagine that the client needs to implement quite a lot of logic to reach the actual endpoint. Any feedback would be very much appreciated. Thanks!
At least part of the issue here is that your API needs to return a media type that supports structured linking (which the usual "REST" API defaults application/json and application/xml do not). To get this support, checkout the HAL or JSONAPI projects.
With a structured linking definition, it becomes much easier to consume - HAL has several libraries to work with it, including a javascript library:
https://github.com/mikekelly/backbone.hal
For an interesting client, checkout the HAL Talk demo.
Yes it is possible. Javascript is just another user-agent.
Yes there is work to do. No I am not aware of any frameworks to do this for you. I have written tooling for supporting hypermedia driving applications on the desktop and I don't consider it a significant amount of work to produce the infrastructure to support hypermedia based applications.
The challenge is less about the tooling and more about the fact that it is a very different approach to building applications. It takes some getting used to.
On a related note there is some ongoing work in the Browser/JS space that will make doing hypermedia driven applications on the client much easier. See NavigatingController.
Currently a JS user-agent can only manage javascript links. With NavigatingController it becomes possible to intercept HTML links also, making JS driven applications much more seamless in the browser.
Related
I'm really confused everytime I come around this question, what characteristics would help one choosing SOAP over REST or the other way around?
I mean, besides the fact that REST has a compact format compared to SOAP, and the other "minor" or "technical" differences, what are the "obvious" differences that make one of them more suitable for a project and not the other?
Just for the record, I have read all of the other questions (1|2|3|4) regarding this matter on Stack Overflow, and not one of them answered my question.
The difference between REST and SOAP is fundamental, yet they're not that dissimilar. Ultimately, you still need to transfer exactly the same information in order to perform a particular abstract operation. It's entirely easy to make REST rather low-performing by choosing poorly what information to return, and SOAP with MTOM can transfer large binary chunks efficiently. There's even the possibility to use non-XML encodings and connected transports (e.g., XMPP) with SOAP that can make it more efficient than REST.
So don't worry about that!
A much more relevant thing to think about is that SOAP continues to have significantly more advanced tooling support in some languages, and that other languages strongly prefer REST. For example, if you want a Java client for your service, you'll be able to get going with SOAP in minutes: just put the WSDL location through a tooling engine and you've got yourself a basic client. On the other hand, if you're working with a Javascript client then you'll absolutely prefer to deal with the REST interface; Javascript works great with REST.
A key thing to note here is that you can have your service support both SOAP and REST at once (you might need to put them on different endpoints, but that's not very onerous). I do this with a service I support (using Java and Apache CXF) and the overhead of doing both is minimal: the key is that I need a clean abstract interface behind the scenes that both the SOAP and REST interfaces use.
If you just want a simple, visual guide to help you measure SOAP and REST against your applications requirements...
Vijay Prasad Gupta has put together a simple, helpful flow-chart.
Direct link to flow chart:
https://drive.google.com/file/d/0B3zMtAq1Rf-sdVFNdThvNmZWRGc/edit
Link to article:
https://www.linkedin.com/pulse/20140818062318-7933571-soap-vs-rest-flowchart-to-determine-the-right-web-services-protocol-for-your-needs
SOAP is a form of RPC and REST is architecture style that can scale with the web.
REST concerns about the following (copied from RESTful Web Services)
Addressability
Statelessness
Representations
Links and Connectedness
The Uniform Interface
Two great books on REST and have some discussions on the topic that you are interested in.
REST in Practice
Restful Web Services
For a SaaS startup I'm involved in, I am building both a RESTful web API and a couple of client apps on different platforms that consume it. I think I've got the API figured out, but now I'm turning to the clients. As I've been reading about REST, I see that a key part of REST is discovery, but there seems to be a lot of debate between two different interpretations of what discovery really means:
Developer discovery: The developer hard-codes copious amounts of API details into the client, such as resource URI's, query parameters, supported HTTP methods, and other details that they've discovered through browsing the docs and experimenting with the API's responses. This type of discovery IMHO necessitates cool linkage and the API versioning question, and leads to hard coupling of the client code to the API. Not much better than if using a well-documented collection of RPC's it seems.
Runtime discovery - The client app itself is able to figure out everything it needs with little or no out-of-band information (presumably, only a knowledge of the media types the API deals with.) Links can be hot. But to make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in. There are possibly other difficulties I haven't thought of yet since I haven't gotten to that point in development. But I do like the idea of loose coupling.
Runtime discovery seems to be the holy grail of REST, but I'm seeing precious little discussion about how to implement such a client. Almost all REST sources I've found seem to assume Developer discovery. Anyone know of some Runtime discovery resources? Best practices? Examples or libraries with real code? I'm working in PHP (Zend Framework) for one client. Objective-C (iOS) for the other.
Is Runtime discovery a realistic goal, given the present set of tools and knowledge in the developer community? I can write my client to treat all of the URI's in an opaque manner, but how to do this most efficiently is a question, especially over low-bandwidth connections. Anyway, URI's are only part of the equation. What about link templating in the Runtime context? How about communicating what methods are supported, aside from making a lot of OPTIONS requests?
This is definitely a tough nut to crack. At Google, we've implemented our Discovery Service that all our new APIs are built against. The TL;DR version is we generate a JSON Schema-like spec that our clients can parse - many of them dynamically.
That results means easier SDK upgrades for the developer and easy/better maintenance for us.
By no means the perfect solution, but many of our devs seem to like.
See link for more details (and make sure to watch the vid.)
Fascinating. What you are describing is basically the HATEOAS principle. What is HATEOAS you ask? Read this: http://en.wikipedia.org/wiki/HATEOAS
In layman's terms, HATEOAS means link following. This approach decouples your client from specific URL's and gives you the flexibility to change your API without breaking anyone.
You did your home work and you got to the heart of it: runtime discovery is holy grail. Don't chase it.
UDDI tells a poignant story of runtime discovery: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
One of the requirements that should be satisfied before you can call an API 'RESTful' is that it should be possible to write a generic client application on top of that API. With the generic client, a user should be able to access all the API's functionality. A generic client is a client application that does not assume that any resource has a specific structure beyond the structure that is defined by the media type. For example, a web browser is a generic client that knows how to interpret HTML, including HTML forms etc.
Now, suppose we have a HTTP/JSON API for a web shop and we want to build a HTML/CSS/JavaScript client that gives our customers an excellent user experience. Would it be a realistic option to let that client be a generic client application? No. We want to provide a specific look-and-feel for every specific data element and every specific application state. We don't want to include all knowledge about these presentation-specifics in the API, on the contrary, the client should define the look and feel and the API should only carry the data. This implies that the client has hard-coded coupling of specific resource elements to specific layouts and user interactions.
Is this the end of HATEOAS and thus the end of REST? Yes and no.
Yes, because if we hard-code knowledge about the API into the client, we loose the benefit of HATEOAS: server-side changes may break the client.
No, for two reasons:
Being "RESTful" is a property of the API, not of the client. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful. The fact that clients don't obey the rules, is not the API's fault. The fact that a generic client would have a lousy user experience is not an issue. Why is it important to know that it is possible to have a generic client, if we don't actually have that generic client? This brings me to the second reason:
A RESTful API offers clients the option to choose how generic they want to be, i.e. how resilient to server-side changes they want to be. Clients which need to provide a great user experience may still be resilient to URI changes, to changes in default values and more. Clients doing batch jobs without user interaction may be resilient to other kinds of changes.
If you are interested in practical examples, checkout my JAREST paper. The last section is about HATEOAS. You will see that with JAREST, even highly interactive and visually attractive clients can be quite resilient to server-side changes, though not 100%.
I think the important point about HATEOAS is not that it is some holy grail client-side, but that it isolates the client from URI changes - it is assumed you are using known (or developer discovered custom) Link Relations that will allow the system to know which link for an object is the editable form. The important point is to use a media type that is hypermedia aware (e.g. HTML, XHTML, etc).
You write:
To make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in.
If that link template is supplied in the previous request, then there is no out-of-band information. For example a HTML search form uses link templating (/search?q=%#) to generate a URL (/search?q=hateoas), but nothing is known by the client (the web browser) other than how to use HTML forms and GET.
GUI based web applications could be build upon a GUI component, stateful framework like Wicket or they could build in a RESTful, stateless way with GUI status only on the client.
From a technical point of view REST looks like the right way since it leverages the full power of http and leads to highly scalable applications. But that comes at a price. Complex GUIs will require a JavaScript application on the client in many cases. You have to stay on the same page and reload only parts, if state should be maintained on the client. Or you have to use tricks with hidden iframes. Sometimes there are pseudo resource like shopping carts on the server, to enable a RESTful design. You have to maintain intermediate state of multi step dialogues and so on ...
If I look around there are very few RESTful GUI webapplications. Is this because of historical reasons or is a RESTful design unproductive in common scenarios?
If I look around there are very few
RESTful GUI webapplications. Is this
because of historical reasons or is a
RESTful design unproductive in common
scenarios?
My answer is subjective, but in my opinion, two major hurdles hinder RESTful development:
Change - it very different from the way sites are traditionally designed
Challenge - designing a pure RESTful server API and a corresponding rich, robust client UI isn't easy
Complex GUIs will require a JavaScript
application on the client in many
cases.
In my opinion, a complex, a rich client-side experience is going to require some in-depth JavaScript, regardless of the server-side implementation.
You have to stay on the same page and
reload only parts,
This is a very different design from the traditional request/response full-page-to-full-page design. Each design has its own trade offs. REST designs work particularly well with AJAX calls, but the client-side code requires careful design to be maintainable and robust.
A RESTful server with a thick-client:
scales well: session information for every user isn't stored in scarce server memory
less request/response data over the wire: not sending every page in full, not sending session IDs or ViewStates
clean reusable URLs: provide a clean, decoupled server API that can support multiple UIs
pure: strict adherence to the HTTP specification (GETs cause no side effects, etc.)
client experience: richer, more responsive with asynchronous transactions
However, as you mentioned thick-clients have drawbacks:
more vulnerable to XSS attacks, RESTful URLs really need careful security
complex JavaScript can be challenging to develop, maintain, and debug (using OO JavaScript can help mediate this)
there is a need to indicate to the user that asynchronous requests are processing in the background
more client-side failure-handling logic is required
frameworks and IDE tools have been traditionally weaker for client-side development, compared to server-side (this is slowly getting better)
RESTful GUI designs are very productive, IMHO. You can leverage a lot of functionality without extra work to support the corner cases, such as the user resubmitting information, browser history (back and forward) multiple tabs and windows. If I'm not mistaken this site uses a RESTful UI.
REST was defined by observing characteristic of successful web applications, both GUI and M2M. Therefore by definition it should be appropriate for these cases.
I also noticed you asked a question regarding desktop versus web applications. You may be interested to know that REST is an excellent architecture for building desktop client applications too. I have written a few desktop clients that get all of their data from a REST server.
This is a multi-part question. I just watched a very interesting presentation on YQL by the lead developer (a graduate of my MS program). While it was very compelling, and I am looking forward to trying it out, I am wondering if anyone knows of alternative frameworks for querying multiple web service APIs to make them appear seamless, the apparent purpose of YQL?
Yahoo's strategy has been to create XML schema definitions that bind a given web service's parameters into their YQL Open Table query parameters, which I think is very clever. Is there any tool that attempts (perhaps I am naive here) to automate the discovery of parameters in say a REST API? I am aware that with SOAP APIs, because there is a published WSDL, it makes automation easier, but is there yet no way to do this with REST? Is anyone trying?
Yes people are trying to produce description languages for REST. The most popular effort is WADL. There are lots of questions about WADL here on SO. Is it a good idea? In my opinion no.
REST does not need a discovery model beyond what it already has with hypermedia, because is trying to solve a problem at a different architectural layer than web services. Web services deliver data to an application's business logic/domain model. REST is about delivering content and behaviour to a presentation layer.
How about an analogy? Think of the different between an object and struct in C++. A struct is just simple data that some client process is going to manipulate. That's what a web service does, it returns a chunk of data, a struct. Sure maybe it did a bunch of server side processing to produce the result, but the end result is a lump of data. A REST interface delivers an object. i.e. It contains both data and the methods that can be used to manipulate that object. By definition, if you understand the uniform interface and you understand the returned media type, you already know what you can do with the response. Discovery mechanisms are redundant.
If you find this hard to believe, the think about the web. How does a web browser discover web pages? The web has no formalized discovery mechanism, and yet there is a world of information out there that we can discover with a web browser.
There is this little website http://zachgrav.es/yql/tablesaw/ which indeed auto-discovers parameters in a REST api and turns it into a YQL compatible table.
There are two ways to find information. Either you use a 100% unambiguous language or you use a natural language. Anything in between like YQL is doomed to fail because it delivers neither and works well only with the examples its authors tout.
I blogged about this at http://zscraper.wordpress.com/2012/05/30/enough-with-crawling-2. My personal stance is that you'll always get the most accurate results if you do your homework first, i.e. study the target domain and figure out how to query it unambiguously.
To answer your question and give you an alternative -- try Bobik. This is a cloud-backed scraping service that you control via REST API. Compose your "queries" in traditional syntax (Bobik supports Javascript, JQuery, XPATH and CSS) and call Bobik to run them from any client-side environment (webpages, mobile apps, or your server).
Hope this helps.
To describe RESTful we can say that every resource has its own URI. Using HTTP GET, POST, PUT and DELETE, we can operate on these resources. All resources are representational. Whoever wants to use our resources can do so via a browser or REST client.
That's the main idea of a RESTful architecture. This architecture allows services on the internet. So why does this architecture need WADL? What does WADL offer that standard HTTP does not? Why does WADL need to exist?
The purpose of WADL is to define a contract. Contract specifies how one party can call another.
When you create a web application from scratch, you don't need contract and WADL.
When you integrate your system with the other system and you can communicate clearly with their development team, you don't need contract and WADL (because you can make a phone call to make things clear).
However when you integrate a complex enterprise system with several others complex enterprise systems maintained by several different companies (or federal institutions), then believe me you want to have a communication contract defined as strictly as possible. Then you need WADL or Open Specification. Need it badly.
People with weak enterprise background tend to see entire IT as a collection of separated web applications developed independently. But enterprise reality is sometimes tough. Sometimes you can't even call or write to the people developing the application you have to integrate with. Sometimes you communicate with a legacy application that is no longer maintained--it just runs and you need to figure out how to communicate with it properly. In such conditions you need a contract because it saves your ass.
Actually client generation is the minor feature of the contract definition. It's just a toy. Contract enforces bad communicators to communicate integration rules clearly. This is the main reason to use WADL or Open Specification or whatever.
Using WADL implies that you just might be gracious enough to actually define the data / documents you are passing back and forth. Say you are passing some XML fragments, they might actually be part of a defined schema.
Whether or not you use the DL to generate code is not very important to me. What matters, in my subjective opinion, is that it is important to have a formal agreement on interfaces between business partners. Even if what is passed is obvious, it helps to identify who has to fix what later if somebody changes the previous interface.
Data format is just as much a part of an interface as verb names.
WADL appeals to people coming from the SOAP world where it is common to use a code generator to create client side code based on the WSDL. I don't think that mechanism is useful in REST as it creates client code that is coupled to server endpoints.
I believe that if you properly define your media-types and use hypermedia within those media-types, then it is not necessary to have WADL. The description of the available end-points is contained within the media-type definitions themselves. And if you are now saying to yourself, but application/xml doesn't contain any information about available hyperlinks, then I say BINGO. That's why I don't think application/xml and application/json are appropriate media-types for REST. I'm not saying don't use XML or JSON, just don't use the generic media type name.
The other appeal of WADL is for the purpose of documenting REST services. Unfortunately, it leads developers down the wrong path as WADL attempts to document server-side end points. Documenting a REST services should focus primarily on the media-types. A client developer should be able to write a REST client without knowing any url other than the root url.
WADL allows you to generate code, tests and documentation. Actually there are few very useful tools utilizing WADL, you can see some examples here. The problem with the "pure" REST, as described in Fielding's dissertation, is writing clients supporting Hypermedia (imagine writing Java Swing-based client application for example). With WADL this task is completely automated, and it's a huge advantage in my view. Testing becomes a way easier too.
Before I give my explanation, let me say that most pure REST extremists will deride it to the ends of the earth. I don't agree with them, as i'd rather get something done, but just so you know.
WADL is a description of a web service API, a little like WSDL is for SOAP type web services, that is designed to be more in tune with RESTful interfaces (something WSDL is poor at).
It's primary usage in my experience is to allow you to generate client code that can call the service (handy if it's a very large API, which literally saves hours of work). It also serves the purpose of documenting a REST-like interface.
REST specifies nothing about WADL.
When you want to expose the REST services ,the best way is to generate WADL and share with consumer(similar to WSDL in SOAP based web services).WADL is used to describe service all in on place.
WADL is not necessary to use. But, If you are working with complex existing application and you want to implement REST service call by replacing the EJB/SOAP service call, Then it is very safe and good practice that you use WADL. By using WADL generate client side java stubs you will be in sync with the service.
You can generate client side java stub using WADL file with help of wadl2java maven plugin.