Rest & RESTful WebServices

Editor's Notes

• #6: Paraphrased from Wikipedia: The REST architectural style describes six constraints applied to the architecture: Uniform interface This is the API of the web service, describing operations and data structures. It simplifies and decouples the architecture of both client and server, enabling each to evolve independently. Client–server decoupling Clients are separated from servers by a uniform interface. For portability, clients must not concern themselves with data storage. For simplicity and scalability, servers must not concern themselves with the UI or user state. Servers and clients may be replaced and developed independently, as long as the interface is not altered. Stateless No client context should be store on the server between requests. Each request contains all of the information necessary to service the request and session state is held in the client. The server can be stateful, but server-side state must be addressable by URL as a resource. This makes servers: More scalable. More visible for monitoring. More reliable in the event of partial network failures Cacheable Clients may cache responses, so responses must define whether they are cachable to prevent clients reusing stale or inappropriate data in response to further requests. Well-managed caching can eliminate repetitive client–server interactions, further improving scalability and performance. Layered system A client’s connection to a server may pass directly to the service or through several intermediaries, allowing: Scalability by enabling load balancing and by providing shared caches The enforcement of security policies. Code on demand (optional) Servers may temporarily extend or customize the functionality of a client by transferring logic to be executed. (e.g. client-side JavaScript) If a service violates any constraint other than “code on demand”, it cannot strictly be referred to as REST web service. Complying with these constraints, and thus conforming to the REST architectural style, will improve a service’s Performance Scalability Simplicity Modifiability Visibility Portability Reliability
• #8: Resource – identified by a URL (or uniform resource locator) Method – the action verb to perform on a resource e.g. GET, POST, PUT, DELETE, etc. Request Headers – name-value pairs of meta-information about the request e.g. Content types expected by the client Request Body – data to be streamed from the client to the server e.g. Attachments, form parameters, etc.
• #9: Note: A REST web service may return the representation of a resource in many formats (HTML, XML, JSON, binary). It is the client’s responsibility to use the “Accept” request header to identify the expected content type of the returned resource.
• #10: Status – An HTTP status code and status message e.g. 404 Not Found, 200 OK Response Headers – name-value pairs of meta-information about the response e.g. Content-Type Response Body – Additional data to be streamed from the server to the client e.g. HTML document, XML document, binary data
• #12: HTTP Methods: GET – The same request URL should return the same resource every time. The request URL should represent a web resource. POST – A generic method for submitting information to the service. The outcome is defined by the service. The request URL need not represent a web resource. PUT – Adds a new resource at the request URL. The resource should then be available through a GET request using the same request URL. DELETE – Removes the resource at the request URL. The resource should no longer be available via a GET request at that URL. OPTIONS – Indicates which HTTP methods are supported at the request URL. Useful for identifying HEAD – Same as GET but only returns meta-information about the resource. The response body will be empty. Useful for requesting information about a resource without having to request the resource itself. Other HTTP verbs are NOT typically supported in a REST service. The above guidelines are required if you wish to remain compliant with the HTTP specification Actual usage of HTTP verbs may vary from implementation to implementation. When producing a service for consumption by a third-party, it is recommended that the service adhere to the HTTP specification Difference between POST and PUT: “The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.” – Emphasis added, W3C HTTP Method specification, referenced at end of presentation Methods Naving No Request Body: GET, DELETE, OPTIONS, HEAD Methods Having a Request Body: POST – body may contain form parameters or other information to be uploaded to the service PUT – body contains the resource to be represented at the request URL Methods Supplying No Response Body HEAD OPTIONS