#1 REST overview
Representational State Transfer or REST is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The term was originated by Roy Fielding, one of the principal authors of the HTTP protocol specification.
Roy Fielding describes REST as:
Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.
The term is also often used in a loose sense to describe any simple interface that transmits domain-specific data over HTTP without an additional messaging layer such as SOAP or session tracking via HTTP cookies. Systems that follow Fielding's REST principles are often referred to as RESTful.
The Web is the key example of existing RESTful design. Much of it conforms or can be made to conform to REST principles. The Web consists of various protocols like HTTP, FTP, HTTPS, SMTP etc, content types including the HTML, XML and other Internet technologies such as the Domain Name Service (DNS).
HTML can include Javascript and Applets that has implicit support for hyper-links. HTTP has a uniform interface for accessing resources which consists of URIs, Request methods (GET, POST, PUT, DELETE), Status codes (401, 404, 500), Headers, and Content distinguished by MIME type (application/plain-text, image/gif, image/png etc.).
HTTP separates the notions of a web server and a web browser. This allows the implementation of each to vary from the other based on the client/server principle. When used RESTfully, HTTP is stateless. Each message contains all the information necessary to understand the request when combined with state at the resource. As a result, neither the client nor the server needs to remember any communication-state between messages. Any state retained by the server must be modeled as a resource.
Before further reading this document, I advise to read this article http://www.xfront.com/REST.html in order to understand REST in proper way.
Let's understand REST in the by taking example of "Camera purchasing store" project. In RESTful application, only single base URL is given to client and after that each representation of resources gives more URLs to be visited and so on. To get information of cameras available on camera purchasing website, a base URL can be given like http://mycamera.com/camera. This can be called as a main resource of available cameras. Calling this resource will result into primary information of available cameras on the website. To obtain more information about each camera link to more resources are provided. They are: http://mycamera.com/camera/view/camera_id/1 and http://mycamera.com.com/camera/view/camera_id/2. Both these resources provides details of respective cameras. These details may also contain links to more resources like 1st resource contains link to another resource http://en.wikipedia.org/wiki/Nikon_D70.
Each of the above request URI is stateless and self-explanatory which means server at any point doesn't require to ask client to provide more information about the request. Moreover each resultant representation provides required information of requested resource as well hyper-link to additional resource attached to main resource.
#2 REST characteristics and principles
#2.1 REST characteristics
Characteristics of the RESTful system would be:
Key principles of RESTful system are:
Note the verb, viewCamera. Instead, use a noun:
http://mycamera.com/camera/view/camera_id/1
To achieve above principles while developing RESTful application, developers will require to start thinking web applications in context of resource and it's representation.
It is not difficult to achieve some of the REST principles, but it is difficult to achieve all of them. For example we hardly use PUT and DELETE methods of HTTP. Below are guidelines about how to achieve them.
Simplest definition between REST and non-REST system is that a system that is not following REST principles is called a non-REST system. That is there is not any specific guidelines or rules to differentiate REST vs. non-REST.
Most of web application are non-REST because it is not possible to create 100% RESTful application due to it's constraints. Often web application needs to use HTTP cookies and Session to keep track of client. Using such components violate REST principle/s (not being stateless). To make application 100% RESTful such information can not be passed in URI due to security reasons.
#4 REST and SOAP
REST can not be directly compared with SOAP as REST is an architectural style while SOAP is a message layer. However RESTful service can be compared with SOAP.
The key difference between REST and SOAP is message style. SOAP is strictly bound to XML while REST doesn't have such constraints hence can use HTML, XML or any other MIME types. Other differences between REST and SOAP are:
REST can use proxy servers in serving contents as resource can easily be identified from URL. Proxies are useful in defining policies of serving resources. Which means if certain resources are not be served, it can be directly denied from there without sending request to actual web server.
On the other hand when resource is requested through SOAP, proxy cannot determine whether resource is to be allowed or not because information of resource is hidden in message envelope. Furthermore the URL is not to the target resource, but rather to a SOAP server which means proxy server will require to look inside each SOAP message to determine what is being asked. To do so proxy server would require to understand semantics of message. Which is difficult task as each SOAP message can have different semantics. However there are other solutions like using RDF/DAML format to allow proxy server to dynamically discover the resource or method to be discovered.
Similar like proxy servers, there are other web intermediaries like gateways, caches etc. which can not be taught to understand semantics of every SOAP message.
On the contrary REST request is self-explanatory hence these web intermediaries can work effectively in serving resources.
Each client application can be considered as a state machine which means each resource representation that it receives causes it to transition to the next state.
In REST based application each representation contains hyper-links; following them puts client into next state. That is there is not endpoint for any state in REST based application.
While in SOAP based implementation each SOAP message is just data i.e no hyper-links which means which resources is to be accessed next must be made out of the band. Following 2 figures gives more details about this difference.
In REST based implementation, caching can play important role in saving bandwidth and increasing response time because each resources has it's own location hence cache servers can easily cache them (if defined in headers) and when new request arrives resource can be served directly from cache.
When resources is requested in SOAP system, message is always sent using POST method even if purpose is to get data. Moreover with SOAP server URI is always same and not the target resource hence a cache server would not know from the URI what resource is being requested. That is with SOAP message, the cache server cannot determine if data is being requested, nor what resource is being requested. Thus no caching possible with SOAP.
In the context of semantic web, according to vision of Tim Berners-Lee, every resource can be given a URI and in fact any resource of significance should be given a URI. The REST architectural style is consistent with this vision due to having unique location for each resource.
While with SOAP, since all requests are submitted at only one SOAP server, it breaks above vision of semantic web.
A key feature of REST (and the Web) is that every resource have a generic interface. Namely, access to every resource is accomplished using HTTP GET, POST, PUT, and DELETE.
With SOAP there is no defined set of methods. Each SOAP application is free to define its own set of methods.
The key to interoperability is standardization. The reason why independent resources on the Web are able to interoperate today is because the Web has standardized on:
#5 REST and Symfony
Since REST is an architectural style and not a standard or a feature, it doesn't depend upon any programming language or framework. However a well designed framework can help a lot in developing RESTful applications.
Symfony framework assists in generating Smart URLs and usage of “/” in URI to represent parent-child relationship through it's routing mechanism (together with Apache web server's mod_rewrite module). Which are important characteristics of a RESTful application.
#6 Examples of REST implementation
Our above example of "Camera purchasing store" is a RESTful web application. Hence we can see some examples of REST principles using HTTP GET and POST methods.
#6.1 Using GET method
For example if users want to retrieve information of available cameras (i.e resources in REST way) from the website, then URL http://mycamera.com/camera provides them list of them and links to see further details of each camera. You can see that it has been implemented using GET method.
This representation contains URL of each camera resource like http://mycamera.com/camera/view/camera_id/1 and http://mycamera.com/camera/view/camera_id/2. Which means data is linked to more data. By visiting above resources user might get links to more camera related resources.
Main resource also provides links to get information about purchase of each camera like http://mycamera.com/camera/purchase/camera_id/1 and http://mycamera.com/camera/purchase/camera_id/2 that is another resources are there. When any of these resources, server returns purchase made for each camera as well as link to other resources like viewing details of each person (http://mycamera.com/user/view/user_id/19) who has purchased particular camera.
#6.2 Using POST method
HTTP POST is an another popular HTTP method to manage resources for any application. As GET is used to retrieve resources from server, POST is used to add/alter/remove resources. Normally POST is used with web forms where user input is required. Hence request submitted through POST method should be handled properly at server side.
RESTful action of POST method for our website is "to purchase cameras”. Consider a base URL http://mycamera.com/camera that provides list of cameras. From this list; link to purchase particular camera can be requested. This link http://mycamera.com/camera/purchase/camera_id/1 is a resource to purchase 1st camera. It will display a form to select desired from and to dates to purchase selected camera. Upon selection and submission of data, camera will get purchased (after making payments etc.). Upon successful submission another resource http://mycamera.com/user is returned which displays confirmation of order made by this user. From this resource order history can be view and deleted if required. Cancellation of order/s (i.e resource) will require another HTTP POST operation.
#6.3 PUT and DELETE methods
DELETE and PUT methods; unlike GET and POST; are not supported by browsers. Hence we have to use POST method to update (PUT) and remove (DELETE) resources in desired way. To do so we may provide PUT and DELETE related information via hidden fields of forms.
Resource http://mycamera.com/user is an example of deleting order which is equivalent to DELETE method while resource http://mycamera.com/user/edit is an example of updating user information which is equivalent to PUT method.
#7 How to create REST based web services
Web services have been designed to share data across many platforms and hardware configurations. For example a web services created on PHP platform can be used by .NET based platform as well as messaging format between client and server is common i.e XML or other HTTP based ones.
Currently there are 3 web services which are popular on the web. They are XML-RPC, SOAP and REST. First 2 services are strictly using XML messaging format while 3rd can use standard HTML, XML, GIF or JPEG etc. In this document important guidelines have been provided to create REST based web-services.
Implementing REST web service correctly requires a resource-oriented view of the world instead of the object-oriented views many developers are familiar with.
In REST based web service resource is the key concept. Hence whole REST web service is designed around managing resources. Since resource requires some mechanism to get identified by web, they are represented by URI.
The creator of a URI decides the encoding of the URI, and users should not derive metadata from the URI itself. URI opacity only applies to the path of a URI. The query string and fragment have special meaning that can be understood by users. There must be a shared vocabulary between a service and its consumers.
A service provider should ignore any query parameters it does not understand during processing. If it needs to consume other services, it should pass all ignored parameters along. This practice allows new functionality to be added without breaking existing services. Here XML schema can be used to validate query parameters.
The resource should be delivered by either of these 4 ways.
A safe service should be invoked by the GET method of HTTP. Parameters needed to invoke the service can be embedded in the query string of a URI. The main purpose of a safe service is to obtain a representation of a resource.
If there is more than one representation available for a resource, the service should negotiate with the client as discussed above. When returning a representation, a service provider should set the HTTP headers that relate to caching policies for better performance.
Obligated services should be implemented using POST. A request to an obligated service should be described by some kind of XML instance, which should be constrained by a schema. The schema should be written in W3C XML Schema or Relax NG. An obligated service should be made idempotent so that if a client is unsure about the state of its request, it can send it again.
Web service should be asynchronous i.e it needs to :
A transaction represents an atomic unit of work done by a server. The goal of a transaction is to complete the work successfully or return to the original state if an error occurs. For example, a transaction in a purchase order service should either place the order successfully or not place the order at all, in which case the client incurs no obligation.
The status resource should not vary much from it's transaction URI. For example:
Life cycle of transaction should be as shown in below image.
While receiving and sending XML, one should follow the principle of strict out and loose in. When sending XML, one must ensure it is validated against the relevant schema. When receiving an XML document, one should only validate the XML against the smallest set of schema that is really needed. Any software agent must not change XML it does not understand.
Typical architectural style of a REST web service could have a pipe-and-filter style. This classical and robust architectural style was used by the famous physicist, Richard Feynman, to build the first atomic bomb in his computing team. It is made of front-end filters, a connector and back-end filters as shown in below image
All front-end filters must be lightweight and must not cause serious resource drain on the host. A common filter is a bouncer filter, which checks the eligibility of the request using some simple techniques:
Back-end filters are usually more application specific or heavy. They should not respond directly to requests but create or update resources.
#8.1 Determining data interchange format
Most REST web services use XML as data interchange format. However it is not necessary to use only XML as different web services might have different requirements. There can be used plain text as well as HTML.
Why XML is used the most is because it is well structured and information can easily be extracted from returned data by using ready made XML parsers. For Plain text and HTML it is difficult to extract certain piece of information unless used at whole.
#8.1.1 Data interchange format and JSON
Apart from XML, JSON is an another popular data interchange format for REST web services. It is Javascript object notation which is used at client side to interpret response in Javascript. Response provided by server can directly be used in JS if web service outputs data in JSON format. JSON:
[head]
[script type="text/javascript" src="converter.php?curr=E&value=3000"]
[/script]
[/head]
[body]
[script type="text/javascript"]
var json=eval(result);
alert(json.value) // Alerts "54.54".
[/script]
[/body]
[/html]
#8.2 Building API
REST API should respect REST principles. Hence while building API, following technical points should be kept in mind.
It is often required to ask users to provide authentication before allowing them to access web service or certain part of web service. There are various ways for to accomplish this task. Since REST architectural style is stateless, we can't ask users to provide valid credentials every time they submit requests. We can have 3 types of solutions.
There are many components of web that exist since long time but were not utilized in best way. REST and Ajax are examples of them. Few years ago web was simple hence people were using REST principles unknowingly. At that time it was not required to have look at them in ordered way. But when web became complex flooding with so many complex techniques, it is again required to make things simple.
REST has been recalled to make things simple. Currently REST is gaining rapid growth because of it's simplicity of implementation and usage over XML-RPC and SOAP. Hence it is the key of next generation web services. Overall, the thing to keep in mind is that REST is about exposing resources through URIs, not services through messaging interfaces.
#10 Links
http://www.xfront.com/REST.ppt
http://en.wikipedia.org/wiki/Representational_State_Transfer
http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
http://rest.blueoxen.net/cgi-bin/wiki.pl?RestFaq
http://www.xfront.com/REST-Web-Services.html
http://www.w3.org/DesignIssues/Axioms.html
http://developer.yahoo.com/maps/rest/V1/geocode.html
http://www.onlamp.com/pub/a/php/2003/07/03/php_amazon_soap.html http://www.onlamp.com/pub/a/php/2003/10/30/amazon_rest.html http://webservices.xml.com/pub/a/ws/2004/03/24/phpws.html
http://www.xml.com/pub/a/2004/08/11/rest.html
http://ajaxpatterns.org/archive/RESTful_Service.php
Representational State Transfer or REST is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The term was originated by Roy Fielding, one of the principal authors of the HTTP protocol specification.
Roy Fielding describes REST as:
Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.
The term is also often used in a loose sense to describe any simple interface that transmits domain-specific data over HTTP without an additional messaging layer such as SOAP or session tracking via HTTP cookies. Systems that follow Fielding's REST principles are often referred to as RESTful.
The Web is the key example of existing RESTful design. Much of it conforms or can be made to conform to REST principles. The Web consists of various protocols like HTTP, FTP, HTTPS, SMTP etc, content types including the HTML, XML and other Internet technologies such as the Domain Name Service (DNS).
HTML can include Javascript and Applets that has implicit support for hyper-links. HTTP has a uniform interface for accessing resources which consists of URIs, Request methods (GET, POST, PUT, DELETE), Status codes (401, 404, 500), Headers, and Content distinguished by MIME type (application/plain-text, image/gif, image/png etc.).
HTTP separates the notions of a web server and a web browser. This allows the implementation of each to vary from the other based on the client/server principle. When used RESTfully, HTTP is stateless. Each message contains all the information necessary to understand the request when combined with state at the resource. As a result, neither the client nor the server needs to remember any communication-state between messages. Any state retained by the server must be modeled as a resource.
Before further reading this document, I advise to read this article http://www.xfront.com/REST.html in order to understand REST in proper way.
Let's understand REST in the by taking example of "Camera purchasing store" project. In RESTful application, only single base URL is given to client and after that each representation of resources gives more URLs to be visited and so on. To get information of cameras available on camera purchasing website, a base URL can be given like http://mycamera.com/camera. This can be called as a main resource of available cameras. Calling this resource will result into primary information of available cameras on the website. To obtain more information about each camera link to more resources are provided. They are: http://mycamera.com/camera/view/camera_id/1 and http://mycamera.com.com/camera/view/camera_id/2. Both these resources provides details of respective cameras. These details may also contain links to more resources like 1st resource contains link to another resource http://en.wikipedia.org/wiki/Nikon_D70.
Each of the above request URI is stateless and self-explanatory which means server at any point doesn't require to ask client to provide more information about the request. Moreover each resultant representation provides required information of requested resource as well hyper-link to additional resource attached to main resource.
#2 REST characteristics and principles
#2.1 REST characteristics
Characteristics of the RESTful system would be:
- Client-Server: a pull-based interaction style: consuming components pull representations.
- Stateless: each request from client to server must contain all the information necessary to understand the request, and cannot take advantage of any stored context on the server.
- Cache: to improve network efficiency responses must be capable of being labelled as cacheable or non-cacheable.
- Uniform interface: all resources are accessed with a generic interface (e.g., GET, POST, PUT, DELETE).
- Named resources - the system is comprised of resources which are named using a URL.
- Interconnected resource representations - the representations of the resources are interconnected using URLs, thereby enabling a client to progress from one state to another.
- Layered components - intermediaries, such as proxy servers, cache servers, gateways, etc, can be inserted between clients and resources to support performance, security, etc.
Key principles of RESTful system are:
- The key to creating Web Services in a REST network (i.e., the Web) is to identify all of the conceptual entities that you wish to expose as services.
- Create a URL to each resource. The resources should be nouns, not verbs. For example, do not use this:
Note the verb, viewCamera. Instead, use a noun:
http://mycamera.com/camera/view/camera_id/1
- Categorize your resources according to whether clients can just receive a representation of the resource, or whether clients can modify (add to) the resource. For the former, make those resources accessible using an HTTP GET. For the later, make those resources accessible using HTTP POST, PUT, and/or DELETE.
- All resources accessible via HTTP GET should be side-effect free. That is, the resource should just return a representation of the resource. Invoking the resource should not result in modifying the resource.
- No man/woman is an island. Likewise, no representation should be an island. In other words, put hyper-links within resource representations to enable clients to drill down for more information, and/or to obtain related information.
- Design to reveal data gradually. Don't reveal everything in a single response document. Provide hyper-links to obtain more details.
- Specify the format of response data using a schema (DTD, W3C Schema, RelaxNG, or Schematron). For those services that require a POST or PUT to it, also provide a schema to specify the format of the response.
- Describe how your services are to be invoked using either a WSDL document, or simply an HTML document.
To achieve above principles while developing RESTful application, developers will require to start thinking web applications in context of resource and it's representation.
It is not difficult to achieve some of the REST principles, but it is difficult to achieve all of them. For example we hardly use PUT and DELETE methods of HTTP. Below are guidelines about how to achieve them.
- Developers should be able to identify all of the conceptual entities that is to be provided as service.
- These entities or resources must have a URI that can represent them.
- The format of URIs should be easy to understand by users. For example prefer noun over verbs i.e use http://mycamera.com/camera/view/camera_id/1 instead of http://mycamera.com/camera/viewCamera.php?camera_id=1.
- Categorize all available resources that are to be exposed so that users can easily find them and visit them one by one.
- Coding should be done in such a way that all resources to be accessed by GET method should remain side-effect free i.e do not modify, delete, alter resources using parameters in GET method like http://mycamera.com/viewUser.php?id_user=1&delete=1.
- In RESTful application, there is not any end-point i.e. Representation of 1 resource leads to access of another resource as shown in camera purchasing example (where list of camera get displayed first, then hyper-link to details of each camera can be accessed from there). However resources need not to be delivered from only 1 domain i.e they can be delivered from different domains also. Even in case of error/s occurring on server while accessing certain resources, server should return status code with proper information that what to do next or what steps to be followed by users so that error/s would not occur again.
- While developing application, data should not get revealed altogether. Which means first generic list of resources should get displayed. That list should contain link to details of each individual resources and so on. The purpose is that daily users might not be interested in seeing details of every resource each time.
- For example in camera purchasing website, URL http://mycamera.com/camera just displays list of cameras. From there, link to details of each individual camera (http://mycamera.com/camera/view/camera_id/1) or purchase of camera (http://mycamera.com/camera/purchase/camera_id/1) can be requested.
- Sometimes different format of data is requested by client; in such case client application should pass desired format related instructions in request directly and server should be able to understand and deliver it according to specifications. For example if details of camera is needed in XML format then query string could be like http://mycamera.com/camera/view/camera_id/1/xml.
Simplest definition between REST and non-REST system is that a system that is not following REST principles is called a non-REST system. That is there is not any specific guidelines or rules to differentiate REST vs. non-REST.
Most of web application are non-REST because it is not possible to create 100% RESTful application due to it's constraints. Often web application needs to use HTTP cookies and Session to keep track of client. Using such components violate REST principle/s (not being stateless). To make application 100% RESTful such information can not be passed in URI due to security reasons.
#4 REST and SOAP
REST can not be directly compared with SOAP as REST is an architectural style while SOAP is a message layer. However RESTful service can be compared with SOAP.
The key difference between REST and SOAP is message style. SOAP is strictly bound to XML while REST doesn't have such constraints hence can use HTML, XML or any other MIME types. Other differences between REST and SOAP are:
REST can use proxy servers in serving contents as resource can easily be identified from URL. Proxies are useful in defining policies of serving resources. Which means if certain resources are not be served, it can be directly denied from there without sending request to actual web server.
On the other hand when resource is requested through SOAP, proxy cannot determine whether resource is to be allowed or not because information of resource is hidden in message envelope. Furthermore the URL is not to the target resource, but rather to a SOAP server which means proxy server will require to look inside each SOAP message to determine what is being asked. To do so proxy server would require to understand semantics of message. Which is difficult task as each SOAP message can have different semantics. However there are other solutions like using RDF/DAML format to allow proxy server to dynamically discover the resource or method to be discovered.
Similar like proxy servers, there are other web intermediaries like gateways, caches etc. which can not be taught to understand semantics of every SOAP message.
On the contrary REST request is self-explanatory hence these web intermediaries can work effectively in serving resources.
Each client application can be considered as a state machine which means each resource representation that it receives causes it to transition to the next state.
In REST based application each representation contains hyper-links; following them puts client into next state. That is there is not endpoint for any state in REST based application.
While in SOAP based implementation each SOAP message is just data i.e no hyper-links which means which resources is to be accessed next must be made out of the band. Following 2 figures gives more details about this difference.
State Transitions in a REST-based Network
State Transitions in a SOAP-based Network
When resources is requested in SOAP system, message is always sent using POST method even if purpose is to get data. Moreover with SOAP server URI is always same and not the target resource hence a cache server would not know from the URI what resource is being requested. That is with SOAP message, the cache server cannot determine if data is being requested, nor what resource is being requested. Thus no caching possible with SOAP.
In the context of semantic web, according to vision of Tim Berners-Lee, every resource can be given a URI and in fact any resource of significance should be given a URI. The REST architectural style is consistent with this vision due to having unique location for each resource.
While with SOAP, since all requests are submitted at only one SOAP server, it breaks above vision of semantic web.
A key feature of REST (and the Web) is that every resource have a generic interface. Namely, access to every resource is accomplished using HTTP GET, POST, PUT, and DELETE.
With SOAP there is no defined set of methods. Each SOAP application is free to define its own set of methods.
The key to interoperability is standardization. The reason why independent resources on the Web are able to interoperate today is because the Web has standardized on:
- Addressing and naming resources -> URI
- Generic resource interface -> HTTP GET, POST, PUT, DELETE
- Resource representations -> HTML, XML, GIF, JPEG, etc
- Media types -> MIME types (text/html, text/plain, etc)
#5 REST and Symfony
Since REST is an architectural style and not a standard or a feature, it doesn't depend upon any programming language or framework. However a well designed framework can help a lot in developing RESTful applications.
Symfony framework assists in generating Smart URLs and usage of “/” in URI to represent parent-child relationship through it's routing mechanism (together with Apache web server's mod_rewrite module). Which are important characteristics of a RESTful application.
#6 Examples of REST implementation
Our above example of "Camera purchasing store" is a RESTful web application. Hence we can see some examples of REST principles using HTTP GET and POST methods.
#6.1 Using GET method
For example if users want to retrieve information of available cameras (i.e resources in REST way) from the website, then URL http://mycamera.com/camera provides them list of them and links to see further details of each camera. You can see that it has been implemented using GET method.
This representation contains URL of each camera resource like http://mycamera.com/camera/view/camera_id/1 and http://mycamera.com/camera/view/camera_id/2. Which means data is linked to more data. By visiting above resources user might get links to more camera related resources.
Main resource also provides links to get information about purchase of each camera like http://mycamera.com/camera/purchase/camera_id/1 and http://mycamera.com/camera/purchase/camera_id/2 that is another resources are there. When any of these resources, server returns purchase made for each camera as well as link to other resources like viewing details of each person (http://mycamera.com/user/view/user_id/19) who has purchased particular camera.
#6.2 Using POST method
HTTP POST is an another popular HTTP method to manage resources for any application. As GET is used to retrieve resources from server, POST is used to add/alter/remove resources. Normally POST is used with web forms where user input is required. Hence request submitted through POST method should be handled properly at server side.
RESTful action of POST method for our website is "to purchase cameras”. Consider a base URL http://mycamera.com/camera that provides list of cameras. From this list; link to purchase particular camera can be requested. This link http://mycamera.com/camera/purchase/camera_id/1 is a resource to purchase 1st camera. It will display a form to select desired from and to dates to purchase selected camera. Upon selection and submission of data, camera will get purchased (after making payments etc.). Upon successful submission another resource http://mycamera.com/user is returned which displays confirmation of order made by this user. From this resource order history can be view and deleted if required. Cancellation of order/s (i.e resource) will require another HTTP POST operation.
#6.3 PUT and DELETE methods
DELETE and PUT methods; unlike GET and POST; are not supported by browsers. Hence we have to use POST method to update (PUT) and remove (DELETE) resources in desired way. To do so we may provide PUT and DELETE related information via hidden fields of forms.
Resource http://mycamera.com/user is an example of deleting order which is equivalent to DELETE method while resource http://mycamera.com/user/edit is an example of updating user information which is equivalent to PUT method.
#7 How to create REST based web services
Web services have been designed to share data across many platforms and hardware configurations. For example a web services created on PHP platform can be used by .NET based platform as well as messaging format between client and server is common i.e XML or other HTTP based ones.
Currently there are 3 web services which are popular on the web. They are XML-RPC, SOAP and REST. First 2 services are strictly using XML messaging format while 3rd can use standard HTML, XML, GIF or JPEG etc. In this document important guidelines have been provided to create REST based web-services.
Implementing REST web service correctly requires a resource-oriented view of the world instead of the object-oriented views many developers are familiar with.
In REST based web service resource is the key concept. Hence whole REST web service is designed around managing resources. Since resource requires some mechanism to get identified by web, they are represented by URI.
The creator of a URI decides the encoding of the URI, and users should not derive metadata from the URI itself. URI opacity only applies to the path of a URI. The query string and fragment have special meaning that can be understood by users. There must be a shared vocabulary between a service and its consumers.
A service provider should ignore any query parameters it does not understand during processing. If it needs to consume other services, it should pass all ignored parameters along. This practice allows new functionality to be added without breaking existing services. Here XML schema can be used to validate query parameters.
The resource should be delivered by either of these 4 ways.
- Server-driven negotiation.
- Client-driven negotiation.
- Proxy-driven negotiation.
- URI-specified representation.
A safe service should be invoked by the GET method of HTTP. Parameters needed to invoke the service can be embedded in the query string of a URI. The main purpose of a safe service is to obtain a representation of a resource.
If there is more than one representation available for a resource, the service should negotiate with the client as discussed above. When returning a representation, a service provider should set the HTTP headers that relate to caching policies for better performance.
Obligated services should be implemented using POST. A request to an obligated service should be described by some kind of XML instance, which should be constrained by a schema. The schema should be written in W3C XML Schema or Relax NG. An obligated service should be made idempotent so that if a client is unsure about the state of its request, it can send it again.
Web service should be asynchronous i.e it needs to :
- Return a receipt immediately upon receiving a request.
- Validate the request.
- If the request if valid, the service must act on the request as soon as possible. It must report an error if the service cannot process the request after a period of time defined in the service contract.
A transaction represents an atomic unit of work done by a server. The goal of a transaction is to complete the work successfully or return to the original state if an error occurs. For example, a transaction in a purchase order service should either place the order successfully or not place the order at all, in which case the client incurs no obligation.
The status resource should not vary much from it's transaction URI. For example:
Transaction URI: http://mycamera.com/xyz1234
Transaction Status URI: http://mycamera.com/xyz1234?option=status
Life cycle of transaction should be as shown in below image.
While receiving and sending XML, one should follow the principle of strict out and loose in. When sending XML, one must ensure it is validated against the relevant schema. When receiving an XML document, one should only validate the XML against the smallest set of schema that is really needed. Any software agent must not change XML it does not understand.
Typical architectural style of a REST web service could have a pipe-and-filter style. This classical and robust architectural style was used by the famous physicist, Richard Feynman, to build the first atomic bomb in his computing team. It is made of front-end filters, a connector and back-end filters as shown in below image
In this style a request is processed by a chain of filters and each filter is responsible for a well-defined unit of work. Those filters are further classified as two distinct groups: front-end and back-end. Front-end filters are responsible to handle common Web service tasks and they must be light weight. Before or at the end of front-end filters, a response is returned to the invoking client.
All front-end filters must be lightweight and must not cause serious resource drain on the host. A common filter is a bouncer filter, which checks the eligibility of the request using some simple techniques:
- IP filtering. Only requests from eligible IPs are allowed.
- URL mapping. Only certain URL patterns are allowed.
- Time-based filtering. A client can only send a certain number of requests per second.
- Cookie-based filtering. A client must have a cookie to be able to access this service.
- Duplication-detection filter. This filter checks the content of a request and determines whether it has received it before. A simple technique is based on the hash value of the received message. However, a more sophisticated technique involves normalizing the contents using an application-specific algorithm.
Back-end filters are usually more application specific or heavy. They should not respond directly to requests but create or update resources.
#8.1 Determining data interchange format
Most REST web services use XML as data interchange format. However it is not necessary to use only XML as different web services might have different requirements. There can be used plain text as well as HTML.
Why XML is used the most is because it is well structured and information can easily be extracted from returned data by using ready made XML parsers. For Plain text and HTML it is difficult to extract certain piece of information unless used at whole.
#8.1.1 Data interchange format and JSON
Apart from XML, JSON is an another popular data interchange format for REST web services. It is Javascript object notation which is used at client side to interpret response in Javascript. Response provided by server can directly be used in JS if web service outputs data in JSON format. JSON:
- conforms REST principles.
- handles simple and complex data types,
- can be used with Ajax and
- can be used at server side.
- Server side implementation
// Class to convert Rupees into Euro, USD and Pound.
class Converter
{
public function convert($curr='E', $value=0)
{
if($curr == 'E')
return ($value / 55);
if($curr == 'D')
return ($value / 44);
if($curr == 'P')
return ($value / 75);
...
}
}
// Create instance.
$converter=new Converter;
// Convert value. When call is made like
// "converter.php?curr=E&value=3000"
$value=$converter->convert($_GET['curr'], $_GET['value']);
// Store result into array.
$result=array('value'=> $value);
// Output JSON encoded string to be used by JS.
echo 'var result='.json_encode($result);
- Client side implementation
[head]
[script type="text/javascript" src="converter.php?curr=E&value=3000"]
[/script]
[/head]
[body]
[script type="text/javascript"]
var json=eval(result);
alert(json.value) // Alerts "54.54".
[/script]
[/body]
[/html]
#8.2 Building API
REST API should respect REST principles. Hence while building API, following technical points should be kept in mind.
- URL of REST web service API should be easy to read and understand and should be self-descriptive. For example for our example project project, URL could be like http://rest.mycamera.com or http://webservice.mycamera.com.
- API can be designed using existing structure of the project so that project's common libraries can also be used.
- REST doesn't constrain how request should be handled at back-end. Hence developers have full control and convenience over design and implementation of API. Therefore only single controller can be used to understand incoming requests. This controller then can call other scripts or code to generate proper response in order to satisfy request.
- Conventions used in scripts and resources should be self-descriptive and easy to navigate in between. For example resource that provides information of particular user could be as simple as like http://rest.mycamera.com/user/XXXX (where XXXX is ID of user). Similarly information of 1st album of this user can be represented by resource like http://rest.mycamera.com/user/XXXX/album/YYYY (where YYYY is ID of 1st album). However for same resource, there can be updation or deletion operations also. This can be determined by type of HTTP request. For example, for URL http://rest.mycamera.com/user/XXXX, if GET method is used then it means information of user has been requested. But if PUT (sometimes POST) method is used then information is to be updated and if DELETE method is used then resource is to be deleted (i.e user is to be deleted).
As we know that handling above type of resources is not easy at server side due to web server constraints, hence frameworks like Symfony (together with URL rewriting mechanism called mod_rewrite for Apache web server) can be used to easily extract operation and values from resources.
- API should be well documented.
- If data transferring between client and server are sensitive then secure HTTP i.e https should be used.
It is often required to ask users to provide authentication before allowing them to access web service or certain part of web service. There are various ways for to accomplish this task. Since REST architectural style is stateless, we can't ask users to provide valid credentials every time they submit requests. We can have 3 types of solutions.
- Standard solution of this problem is to use HTTP authentication. Once user is authenticated, he/she will just need to provide valid token for validation instead of providing credential every time. This token can then be used to response subsequent requests.
- Another approach is to use Session mechanism that PHP provides. Once API validates users' credentials, it should create session for associate user. PHP then issues a session ID (referred as PHPSESSID) that can be used to associate particular user with existing session on server. This session ID is stored in form of cookie at user side (if user has enabled cookies) and will be read directly from there by PHP's session mechanism. If cookies are disabled (or not accepted) then this session ID can be appended to query string each time new request is made to web service. PHP stores sessions in form of files at specified folders (usually /tmp). This session ID stores user's information such as browser's user agent, IP address of user's machine etc. which means even if someone else tries to use this session ID to act as authenticated user, he/she can't do so. Moreover, by default, upon inactivity, these session IDs are destroyed after 20 minutes which means in future also none can use it.
- 3rd solutions is to use customized interface to authenticate users. For that database storage system can be used where user's information can be stored. When user submits request 1st time, he/she will require to provide ID and Password to log on web service. At server side API will do authentication and will issue a unique hash or token back to user to be used for subsequent requests. This hash will be appended to request URL every time new request will be made. At server side this hash or token will be stored in database along with other information of user for future validations. By this way we can increase/decrease inactivity time out, can store more information about user and can retain certain information of client for logging purpose etc.
There are many components of web that exist since long time but were not utilized in best way. REST and Ajax are examples of them. Few years ago web was simple hence people were using REST principles unknowingly. At that time it was not required to have look at them in ordered way. But when web became complex flooding with so many complex techniques, it is again required to make things simple.
REST has been recalled to make things simple. Currently REST is gaining rapid growth because of it's simplicity of implementation and usage over XML-RPC and SOAP. Hence it is the key of next generation web services. Overall, the thing to keep in mind is that REST is about exposing resources through URIs, not services through messaging interfaces.
#10 Links
http://www.xfront.com/REST.ppt
http://en.wikipedia.org/wiki/Representational_State_Transfer
http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
http://rest.blueoxen.net/cgi-bin/wiki.pl?RestFaq
http://www.xfront.com/REST-Web-Services.html
http://www.w3.org/DesignIssues/Axioms.html
http://developer.yahoo.com/maps/rest/V1/geocode.html
http://www.onlamp.com/pub/a/php/2003/07/03/php_amazon_soap.html http://www.onlamp.com/pub/a/php/2003/10/30/amazon_rest.html http://webservices.xml.com/pub/a/ws/2004/03/24/phpws.html
http://www.xml.com/pub/a/2004/08/11/rest.html
http://ajaxpatterns.org/archive/RESTful_Service.php
