RESTful Web services: Basics

Representational State Transfer (REST) has gained widespread acceptance across the Web as a simpler alternative to SOAP- and Web Services Description Language (WSDL)-based Web services. Key evidence of this shift in interface design is the adoption of REST by mainstream Web 2.0 service providers—including Yahoo, Google, and Facebook—who have deprecated or passed on SOAP and WSDL-based interfaces in favour of an easier-to-use, resource-oriented model to expose their services.

Basics Fundamental

REST didn't attract this much attention when it was first introduced in 2000 by Roy Fielding at the University of California, Irvine, in his academic dissertation, "Architectural Styles and the Design of Network-based Software Architectures," which analyzes a set of software architecture principles that use the Web as a platform for distributed computing.

When it's attracting this much attention, a concrete implementation of a REST Web service follows four basic design principles:

• Use HTTP methods explicitly.
• Be stateless.
• Expose directory structure-like URIs.
• Transfer XML, JavaScript Object Notation (JSON), or both.

Some soft guidelines for designing a REST architecture:

1. Do not use "physical" URLs. A physical URL points at something physical -- e.g., an XML file: "http://www.sanjeevrathaur.com/inventory/prod008.xml". A logical URL does not imply a physical file: "http://www.sanjeevrathaur.com/inventory/product/008".

• Sure, even with the .xml extension, the content could be dynamically generated. But it should be "humanly visible" that the URL is logical and not physical.

2. Queries should not return an overload of data. If needed, provide a paging mechanism. For example, a "product list" GET request should return the first nproducts (e.g., the first 10), with next/prev links.

3. Even though the REST response can be anything, make sure it's well documented, and do not change the output format lightly (since it will break existing clients).

• Remember, even if the output is human-readable, your clients aren't human users.
• If the output is in XML, make sure you document it with a schema or a DTD.

4. Rather than letting clients construct URLs for additional actions, include the actual URLs with REST responses. For example, a "product list" request could return an ID per product, and the specification says that you should use http://www.sanjeevrathaur.com/product/PRODUCT_ID to get additional details. That's bad design. Rather, the response should include the actual URL with each item: http://www.sanjeevrathaur.com/product/001263, etc.

• Yes, this means that the output is larger. But it also means that you can easily direct clients to new URLs as needed, without requiring a change in client code.

5. GET access requests should never cause a state change. Anything that changes the server state should be a POST request (or other HTTP verbs, such as DELETE).

Establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods. According to this mapping:

• To create a resource on the server, use POST.
• To retrieve a resource, use GET.
• To change the state of a resource or to update it, use PUT.
• To remove or delete a resource, use DELETE.

Enjoy !!!!!!!!!!!!!