I really can't get the difference between REST and POX web services. I mean, couldn't POX be considered as a REST web service with XML message definitions?
It depends on what your "Plain Old XML" contains.
The thing is, POX used to be compared with SOAP. SOAP is a very specific way to do XML over (mostly) HTTP and people were already doing "plain old XML" over HTTP. SOAP got a lot of criticism because it complicated the things people were already doing with POX. But I won't go into that, what I'm trying to say is that people used POX to do RPC.
REST isn't RPC. In REST, the XML is a representation of a resource, not a message definition as in RPC. There is also a very important REST constraint that people seem to forget or ignore that imposes constraints on the returned XML: the hypermedia constraint or HATEOAS.
If you want to find out more about how POX fits in REST, I recommend reading this article: Richardson Maturity Model, steps toward the glory of REST.
Related
In REST URIs should be opaque to the client.
But when you build interactive javascript-based web-client for your application you actually have two clients! One for interaction with server and other one for users (actual GUI). Of course you will want to have friendly URIs, good enough to answer the question "where am I now?".
It's easier when a server just respond with HTML so people can just click on links and don't care about structure. Server provides URIs, server receives URIs.
It's easier with desktop client. The same staff. Just a button "show the resource" and user doesn't care what the URI is.
It's complicated with browser clients. There is the address bar. This leads to the fact that low-level part of web-client relies on the URIs structure of a server. Which is not RESTful.
It seems like the space between frontend and backend of the application is too tight for REST.
Does it mean that REST is not a good choice for reactive interactive js-based browser clients?
I think you're a little confused...
First of all, your initial assumption is flawed. URI opacity doesn't mean URIs have to be cryptic. It only means that clients should not rely on URI semantics for interaction. Friendly URIs are not only allowed, they are encouraged for the exact same reason you talk about: it's easier for developers to know what's going on.
Roy Fielding made that clear in the REST mailing list years ago, but it seems like that's a myth that won't go away easily:
REST does not require that a URI be opaque. The only place where the
word opaque occurs in my dissertation is where I complain about the
opaqueness of cookies. In fact, RESTful applications are, at all
times, encouraged to use human-meaningful, hierarchical identifiers in
order to maximize the serendipitous use of the information beyond what
is anticipated by the original application.
Second, you say it's easier when a server just respond with HTML so people can just follow links and don't care about structure. Well, that's exactly what REST is supposed to do. REST is merely a more formal and abstract definition of the architecture style of the web itself. Do some research on REST and HATEOAS.
Finally, to answer your question, whether REST is a good choice for you is not determined by client implementation details like that. You can have js-based clients, no problem, but the need to do that isn't reason enough to worry too much about getting REST right. REST is a good choice if you have projects with long term integration, maintainability and evolution goals. If you need something quick, that won't change a lot, or won't be integrated with a lot of different clients and services, don't worry too much about REST.
I have to implement "service bindings" in a project in my school.
I just learned WSDL from w3schools.com. I came to know that "WSDL" is. I know WSDL but I didn't do anything with it. I want to go practical with it. I don't know how to do that.
From where to start? I know there are other things to learn and I don't know what are they.
I need some help in getting "practical". Its just in my mind I don't know how to implement it.
Based on your question I assume you are a little bit confused. You should talk to you teacher (or whoever gave you this assignment) and find what is expected for you to do.
Web services involve a lot of knowledge, WSDL is just one part of it.
As you probably have learned from w3schools, WSDL means Web Services Description Language. It is a way to document a web service's interface to the world.
A web service is accessible from an endpoint address, something like
http://some.server.com/context/bla/whatever
This tells you where to find the web service, it tells you nothing about how to call it (i.e. how are the messages going to be structured for a correct communication).
The WSDL provides you this info: what operations are exposed, how messages are composed, binding used etc.
So that you understand a bit how WSDL "fits" in the entire picture I'm going to use a little story.
Let's say some company wants to offer some online services. They expose these services as a SOAP web service and make it available at address http://some.server.com/context/bla/whatever.
After they advertise their services they have to actually tell their customer how to use the thing. They could send them an e-mail and tell them how to call it or they can write a Word document and tell them how to do it. But that is not practical, and a mail or word document can't be used to generate client code automatically. Some dude will have to write the code by hand... poor bastard.
This is where WSDL comes into play. It is a specification which describes the interface to the service. Beeing an XML file it is a human readable format but more importantly is a format that a machine can read and process and... as you probably guessed by now... can generate client code based on it.
As such, the company does not bother to write e-mails or documents. They document everything in a WSDL file and make that available online (the XML Schema types inside the WSDL... very important... you should read XML Schema).
To simplify things even more you can (usually) find the WSDL at the same address as the web service with just an extra parameter added:
http://some.server.com/context/bla/whatever?wsdl
Based on the WSDL the clients can now generate code that can call the service (in C# with svcutil.exe, in Java with Axis wsdl2code etc).
And Price Charming and Cinderella lived happily ever after... oh... wait.. that's another story :P.
Seriously now.... as I said at the beginning: Talk to you teacher and ask how you are supposed to get practical with WSDL.
Hope this explanation makes it a little bit clearer for you.
okay this might be a pretty lame and basic question but its stuck in my head since i never had chance to work on web-services.
We can get the same "text bases" response(xml, json etc) from our server by very basic/simple implementations (lets say servlet) then why do someone has to develop a web-service.
What is the exception thing a web-service gives over simple http response?
At a basic level, you are quite correct, from a low level point of view, it's just text (XML) on a socket.
For simple web services, a servlet is adequate (I'm writing one of these as we speak).
When talking about something like SOAP and WSS-* web services, however, there is a lot of boiler plate processing and features available from the standards that web service toolkits expose as higher level transactions.
A simple example is data marshaling. If you treat it purely as XML, then your service basically gets to process the XML by hand -- parse it, evaluate it, populate your internal models, etc.
Contrast this to something like this from Java EE:
#WebService
public Person getPerson(String personId) {
Person p;
...
return p;
}
The web service stack will convert your Person object in to a SOAP compliant XML blob. It will also produce a WSDL that you can use to create client code (on many platforms: .NET, PHP, etc.) to make the web service code.
In the end, your client and server have only a few lines of code, while the frameworks do all of the grunt work parsing, marshaling, and publishing for you.
So, the value of the WS stack is that it handles much of the bureaucracy of writing WSS compliant web services.
It's no panacea, but for many modern implementations, SOAP <-> SOAP remote processing can be a, mostly, cross platform, drag and drop affair.
It depends. If your web service needs to answer a simple yes/no question like "does this username exist?", then return yes, no, 0, 1, etc may be enough. If you have one that returns all the faculty attributes, XML or JSON may be appropriate because of the structured nature. It's a little less prone to parsing errors than trying to parse plain text.
I have what seems to be a fairly simple question about implementing a data access client that strictly adheres to REST architectural principles. To start, let's assume I have a well-behaving REST API that I want to consume using a Django application. I'll start by discovering what services are available (edited for follow-up):
GET example.com/services/ HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<services>
<service>
<name>Widgets</name>
<link>http://example.com/services/widgets/</link>
<item_link>http://example.com/services/widgets/{widget_id}/</item_link>
</service>
<service>
<name>Factories</name>
<link>http://example.com/services/factories/</link>
<item_link>http://example.com/services/factories/{factory_id}/</item_link>
</service>
...
</services>
Now, since I'm building a Django application based around consuming this API, how would I continue to keep exploring these services RESTfully? To adhere to REST principles, my application must be driven by the hypermedia received. I suppose the first step is easy enough -- interacting with a service by the name given. I set up a Django view as follows:
def get_service(request, service_name):
doc = etree.parse(urllib.urlopen('http://example.com/services/'))
uri = doc.xpath("service/name[.='%s']/following-sibling::*" % service_name)[0].text
...
From which I'll perform another request (edited for follow-up):
GET example.com/services/widgets/ HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<widgets>
<item_link>http://example.com/services/widgets/{widget_id}/</item_link>
<widget>
<id>1</id>
<name>Whizbang Foobar</name>
<link>http://example.com/services/widgets/1</link>
</widget>
...
</widgets>
Now I'll display a simple list of widgets in a rendered Django template. From here though, how do I continue to interact with this service RESTfully? Perhaps I've befuddled myself into confusion, but the only reasonable things I can come up with are implementing a numerous amount of application views or a thin Django data model to persist the service URI.
My main concern boils down to that this is trivial to do without strictly adhering to REST architectural guidelines, but I feel like I've missed the boat completely in trying to do so. I understand designing proper REST APIs and clients isn't "easy", but it seems that I'm in dire need of a similar example to work through the actual implementation.
I apologize for the length and verbosity of the question and the inevitable facepalming of wizened readers.
Follow-up:
Is the following a valid way (using URI templates) of implementing these interactions? For demonstration purposes (in lieu of a more abstract implementation), another Django view to retrieve a resource collection item:
def get_item(request, service_name, item_id):
doc = etree.parse(urllib.urlopen('http://example.com/services/'))
uri = doc.xpath("service/name[.='%s']/following-sibling::item_link" % service_name)[0].text
...
Then the subsequent request:
GET example.com/services/widgets/1 HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<widget>
<id>1</id>
<name>Whizbang Foobar</name>
<tags>foo bar baz ham eggs</tags>
<index_link>http://example.com/services/widgets/</index_link>
</widget>
My main concern boils down to that this is trivial to do without strictly adhering to REST architectural guidelines, but I feel like I've missed the boat completely in trying to do so. I understand designing proper REST APIs and clients isn't "easy", but it seems that I'm in dire need of a similar example to work through the actual implementation.
The best example I've been able to find is the Sun Cloud API. Most of the documentation describes the various media types used by the system, which seems to be the key to pulling this kind of thing off.
I find that it helps to be writing your client at the same time you're developing your API. That way you can spot what's likely to make your API a pain to code for right away and fix the problem.
It isn't easy. If you follow the HATEOAS constraint to its logical conclusion, each media type you define will be handled by one of a family of clients. To the extent that you can make all of your resources follow a similar pattern of behavior, your job of writing clients will become easier.
For example, you could define a media type 'Index' that simply lists related resources. Index defines links for pagination, getting items in the list, finding items by name, etc.
Then, you might define a base media type called 'Item'. Item has a link for displaying its parent Index, updating/deleting itself, etc. Your resource Widget could then be represented by two different media types - one Index and one based on Item.
You could begin by implementing a single class that handles the Index media type. Then you could write a base class that handles all common Item media type behavior. Finally, you could write a Widget client that handles all widget-specific behavior and which extends the Item client. These clients could expose their functionality (availability of more links and data fields) in an idiomatic way for the language they're written in.
Processing a response from your server would then be a matter of matching the mime type of the response to one of the clients you've written.
In other words, even though the client for your service as a whole would be made up of many clients of limited scope, they would each be based on common behaviors and so could be implemented in a DRY way.
From my experience the REST model makes much more sense if the representations and their contained links are translated directly to a client UI. In this scenario it is the user that directs the exploring of the REST interface.
Often I see people trying to use REST interfaces as a kind of HTTP based data access layer. With this mental model, hyperlinked data provides little more than structural data relationships. It becomes difficult to build application behaviour on top of that interface without violating RESTful constraints.
I like to think of a RESTful interface as delivering UI content to an application that is going to render that content with some arbitrary technology. Unfortunately, REST is frequently compared to web services which, in my opinion, fit in a different architectural layer. Web services deliver data that is to be processed by a client application. RESTful interfaces should deliver content that will be rendered to the user.
Sure you can use a REST interface to deliver data to remote applications but think of it as simplified screen scraping.
When writing a client for REST interface I find it useful to imagine that I am writing a custom web browser that only understands the media-types that are delivered by that RESTful interface and is hard-coded to start at a specific URL and there is no address bar!
Sun Cloud API documentation is a great example of a RESTful API, focusing on the media types.
If I understand your question correctly, you want to explore an unknown service, correct?
If so, then you could, for example continue with an OPTIONS request to the "widget" resource, to see which HTTP methods it supports (these should be listed in the Allow header of the response).
You can then do the same for all URIs found in <link rel="whatever"> elements. If a resource found this way indicates that it supports GET, then fetch it and repeat ...
This way you should be able to explore all nested resources.
This kind of exploration will of course only get you so far, because to really interact with the service, you will need to know about its media types (or representations), and what the different <link rel="whatever"> actions you found actually mean. This step can't be automated, you'll have to read the documentation for the service and build you client accordingly. I suggest reading the article "How to GET a Cup of Coffee", which I think explains this interaction very well.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 6 years ago.
Improve this question
Most REST interfaces I see are described with a simple web page describing the URL, the method, accepted input and returned result. For example the Amazon S3 or the Twitter API documentation.
Human readable is apparently good enough for Amazon or Twitter. However are there any companies describing a REST API in a machine readable format? And if yes, which ones?
WSDL 2.0 claims is capable of describing REST. WADL is explicitly created for describing REST services. Both WSDL 2.0 and WADL seem to have a rather small following atm and it seem to be little return for the effort of creating and maintaining the description documents. By identifying real life examples it is basically possible to validate or negate this assumption.
Do you use WSDL/WADL to describe your services? Do you rely on WSDL/WADL to consume others' services? Does your tool of choice support either one at the moment? Are there any examples of broadly used REST services that can be used that are detailed in a machine readable format?
Yes, you should. You will be able to generate your client code, tests and documentation using a set of tools supporting WADL. Some examples can be found here. Also, I think you should stick with WADL, rather than WSDL 2.0 because it is less verbose and way simpler (IMHO). In fact, in WADL you describe exactly what the user sees on the documentation page, just using WADL XML syntax. BTW, that is why it's so easy to write XSLT-based documentation generators for WADL.
The following is just my personal opinion:
I think WADL is similar to site maps for html pages. Site maps are considered theoretically a good practice, but rarely implemented and even more rarely used by people.
I think the reason is simple - wandering around a site and pushing strategically placed buttons is often significantly more rewarding than browsing a complex map.
REST API methods should not require a formal description. So if API is created thoughtfully it is pretty easy to discover all the resources just by following strategically placed uri links of a 'home' RESTful resource.
There's a chicken/egg phenonenon here. WADL is useless without tools that produce or consume it. The tools are useless unless sites publish WADL. etc.
For me, The Amazon model works fine. Depending on your audience you will get more return on an effort to produce samples, including snips od sample dialogs (what does request1 look like on the wire, same for response 1, then request 2, response 2, etc), and code in vvarious languages that are important to you. If you want to go to a machine-readable definition, you can use XSD if it is an XML message format. Obviously this is not WADL but coupled with your english description, it may provide a little extra utility for developers.
What is the benefit of a machine-readable REST API definition?
The point of REST is for the API to be relatively simple and easy-to-understand. Natural language works well for this.
If you mean "API Type Definitions" when you say "API Definition" then there may be some value in providing metadata. This, however, is only one piece of an API definition.
Having "machine readable" API can easily repeat the API source code, violating the DRY principle.
It's often simpler to write English descriptions of what the REST verbs do and what the URI's are. Send the type's which are marshalled through JSON (or YAML or JAXB) as source code. That's the perfect machine-readable API -- actual working source for the message object class.
The most popular usage of WSDL (and WADL in the same way) is code generation. It sure helps speed up development, but nothing can replace plain old documentation. For humans and not for machines.