A server response in REST is often an XML file; for example,
<parts-list> <part id="3322"> <name>ACME Boomerang</name> <desc> Used by Coyote in <i>Zoom at the Top</i>, 1962 </desc> <price currency="usd" quantity="1">17.32</price> <uri>http://www.acme.com/parts/3322</uri> </part> <part id="783"> <name>ACME Dehydrated Boulders</name> <desc> Used by Coyote in <i>Scrambled Aches</i>, 1957 </desc> <price currency="usd" quantity="pack">19.95</price> <uri>http://www.acme.com/parts/783</uri> </part> </parts-list>
However, other formats can also be used; unlike SOAP services, REST is not bound to XML in any way. Possible formats include CSV (comma-separated values) and JSON (JavaScript Object Notation).
Each format has its own advantages and disadvantages. XML is easy to expand (clients should ignore unfamiliar fields) and is type-safe; CSV is more compact; and JSON is trivial to parse in JavaScript clients (and easy to parse in other languages, too).
One option is not acceptable as a REST response format, except in very specific cases: HTML, or any other format which is meant for human consumption and is not easily processed by clients. The specific exception is, of course, when the REST service is documented to return a human-readable document; and when viewing the entire WWW as a RESTful application, we find that HTML is in fact the most common REST response format...
18 comments:
So how do you request different types of responses? For example, the same REST service can serve up both XML and CSV. Where do you stick the requested type in the request?
Hi mjuchems,
The best alternative is probably to use a different URL for each -- e.g., a different path on the server. For example, http://www.example.com/products/12345 vs. http://www.example.com/products/csv/12345 (where the shorter format is used for the "default", or preferred, output format -- note the "csv" in the second URL).
Proper server configuration (e.g., in Apache) can help you implement this using a single server script, which gets the extra path data as a parameter.
Another alternative is passing the format as parameter directly; something like, the default is XML, but add "?format=csv" to get CSV output.
Hi Dr. Elkstein, GREAT tutorial!
On the question by mjuchems, isn't it possible to use the same URL for different formats, and let the client negotiate the content type by request headers or something like that?
Hi Dario,
Indeed, it is possible to specify the desired output type in the HTTP "Accept" request header. However, personally, I prefer (for read-access-only REST requests) to be able to issue the request directly from the browser. I find that this makes debugging significantly easier. And since, in the browser, you can't easily change the HTTP headers, using a URL argument is the alternative I prefer.
Actually one thing that comes to my mind is the use of MIME types as part of URL, just the same way as in Accept header. You can make it optional and use that whole thing out of anywhere you want including web browser.
I thought that one constraint from the uniform interface feature of REST is that the messages have to be self-describing. As I understand it, that means, one has to include at least (a) reference(s) to the namespace(s) that explain(s) the utilized terms (cf. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven).
Hello zazi,
Unlike SOAP-based web services, REST is, by definition, not very rigid. This means that, when you write a REST service, you can choose to include references to said namespaces and definitions, but nothing says you have to. Of course, a service that does offer such references can be more useful, or easier to use. But it's certainly not a strict requirement.
Note spelling error in first sentence.
Thanks, Dave -- corrected.
You mention that using XML affords type safety, how is this achieved? XML does not know anything of type, the attributes are string values as well as the node values.
How do you know this is a number?
14
Hello Mader,
To find out about typing in XML, read about schema specification mechanisms, such as XSD, RelaxNG, etc.
I do not understand:
One option is not acceptable as a REST response format, ...., we find that HTML is in fact the most common REST response format...
the last paragraph.
Hi Antanas,
First, I explicitly limited my preference for standard headers to read-only requests; so your comment about put/delete requests is unrelated.
And, in some contexts, yes, the ability to test things from a browser is important. When a client calls to complain that things don't work as expected, it's very handy to be able to ask him to open that page from a browser and send me the output, for example.
Great Tutorial even in 2013
Hi Dr.Elkstein, great Tutorial, first of all.
Can you point out the disadvantages of using XML,CSV and JSON. I believe you only mention advantages.
Hi Piloto,
XML, CSV, and JSON all have their disadvantages, obviously. The most clear disadvantage is shared by all three, though: they are text formats. This is very beneficial in most scenarios: ever so much easier to read, understand, and debug these formats, compared to binary formats. However, when very large amounts of traffic are involved, using binary formats can both save bandwidth and reduce CPU processing required to parse responses. For example, Google use an internally-developed format called Protocol Buffers for inter-server communications, mostly for this exact reason. Protocol buffers (available in open source) were explicitly designed to be smaller and faster than XML.
Please clarify "One option is not acceptable as a REST response format... " as we know HTML is used more frequently for response.
Thanks ELKSTEIN,
Good explanation And comments replay.
Post a Comment