Inputs and Outputs for RESTful Services
REST accepts plain text-based, discrete HTTP query parameters as inputs for the state information into a resource. For example, if you want to update your shipment (tracking number 1234567890) with the date and the location of the delivery, you would POST the following query parameters to the 1234567890 URI:
Unlike other web services standards, nothing in REST mandates using XML or any other input type. It is perfectly fine and appropriate to use an HTTP query string to query or update the state of the web-accessible resource. However, query strings should not be used to identify the resources themselves, only to query or update their states.
The only acceptable REST method for identifying and accessing resources is via URI:
You should never identify resources via query parameters like this:
For output, REST promotes using standard HTTP status codes. For example, when an update to a resource is issued via POST, the Shipment servlet will respond with either HTTP OK or HTTP ERROR code:
resp.setStatus( HttpServletResponse.SC_OK );
In the case of the GET method issued against the resource, the Shipment servlet will transfer the state to the client using the following XML:
With REST, all standard information formats such as (X)HTML, XML, JPEG, GIF, etc. are valid resource representations. In practice, it is common to use query parameters as the input for resource methods, and XML as the output from the methods that produce rich state representation (e.g., GET).
Web Services for Developers
REST architectural style deserves the attention of any developer or architect who is interested in solving common interoperability problems in the simplest and most pragmatic fashion. Specifically, it is hard to ignore REST’s very specific and very attractive propositions when it comes to establishing a web-based, interoperable infrastructure:
- It promotes the reuse of well-established protocols, APIs, and infrastructure.
- It promotes a pragmatic and simplistic approach to application design.
The architectural values and productivity that the REST style promotes have led many to call RESTful web services the web services for developers. This article was a brief and practical introduction to getting started with RESTful web services.
Numerous debates are taking place on the web about which is the better approach for web services, REST or SOAP. This article left those debates alone, but I strongly advise you to read the additional material on REST provided in the Related Resources section in the left column. These great readings cover not only REST but web architectures and pragmatic development as well.