The previous section included a simple example for a REST request -- with a single parameter.
REST can easily handle more complex requests, including multiple parameters. In most cases, you'll just use HTTP GET parameters in the URL.
For example:
http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe
If you need to pass long parameters, or binary ones, you'd normally use HTTP POST requests, and include the parameters in the POST body.
As a rule, GET requests should be for read-only queries; they should not change the state of the server and its data. For creation, updating, and deleting data, use POST requests. (POST can also be used for read-only queries, as noted above, when complex parameters are required.)
- In a way, this web page (like most others) can be viewed as offering services via a REST API; you use a GET request to read data, and a POST request to post a comment -- where more and longer parameters are required.
While REST services might use XML in their responses (as one way of organizing structured data), REST requests rarely use XML. As shown above, in most cases, request parameters are simple, and there is no need for the overhead of XML.
- One advantage of using XML is type safety. However, in a stateless system like REST, you should always verify the validity of your input, XML or otherwise!
8 comments:
>REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol
>One advantage of using XML is type safety. However, in a stateless system like REST, you should always verify the validity of your input, XML or otherwise!
What does "stateless" system mean?
Hi Mangol,
Generally speaking, "stateless" means the server does not maintain state information per-client. For a simple example, consider a file-reading service. One possible API is of the kind common in most programming languages, with functions like FileOpen and FileRead, that can be used like this:
File f = FileOpen("myfile.dat");
byte[] firstK = FileRead(f, 1024);
byte[] secondK = FileRead(f, 1024);
In this pseudo-code, firstK will contain the first 1,024 bytes, and secondK will contain the next 1,024 bytes. But note how both were created using the exact same function call, with the exact same argument list! This happens because the system "remembers", for each open file, where is the "file read head"; this is the state, in this case.
By comparison, a stateless API can be used to achieve the same results, like this (again in pseudo-code):
firstK = FileRead("myfile.dat", 0, 1024);
secondK = FileRead("myfile.dat", 1024, 1024);
Here, the FileRead function accepts the filename, where to start, and the amount to read; there is no "state" associated with the file, and invoking the exact same command twice will yield the exact same result (assuming the file itself was not chagned, of course).
Clearly, stateless APIs make little sense for local file-reading functions; but they do make a lot of sense in a web-based API. The three key benefits are:
(a) Surviving a server restart. If the server had to remember per-client state, a restart would mean all the state data is lost. But with a stateless server, clients don't care if the server was rebooted.
(b) No client-to-server binding; the requests can be handled by a cluster of servers, and each request can be handled by a different machine in the cluster (no "server affinity" for the clients). In a stateful API, either the exact same machine has to handle all requests by the same client, or else the state of all clients must be replicated across all servers.
(c) Increased scalability. In HTTP, the server never knows if and when the client will issue the next request. Maintaining state for numerous clients can impose a strain on server resources (mainly memory), and stateful systems use a time-out mechanism to end sessions where the clients take too much time between requests. There's no such problem if the server is stateless.
Is a true Stateless server possible? Even for authentication with a token mechanism, the server needs to remember atleast the credentials. So, the timeout and expiry in such a case is still applicable. Also, these credentials needs to be shared between servers in a scaled architecture. Could you please throw some light on how this is taken care of?
Hi "thethinker",
There are several ways to do that... One is to introduce state just for login credentials, as you noted. Another is have a smart-token: something that includes the username, an expiration timestamp, and a digital signature of both, for example -- so it can be verified by the server, statelessly.
For multi-server setups, server affinity (by IP, or using cookies) is sometimes used. Of course, the cookie-based approach might fail for REST, since many clients are not browsers and will not respect cookie requests. Other than that, either of the two options presented above (shared storage for user state data or signed tokens) could work.
Simple and beautiful article
Great and Simple Examples. I was looking for a basic understanding of what REST is and the URI example versus the SOAP package, plus the envelope and postcard are the best examples I've seen. I read another article for 30 minutes; and still didn't have a clear understanding of the difference or its purpose; with this; I understood it in 3 minutes.
Thank you.
Great Tutorial! Thank you for creating this site.
What an Idea Thank you. Your tutorial so much helpful
Post a Comment