web services by ronaldtamarind


More Info
									                                      REST (representational state transfer)
REST (representational state transfer) is an approach for getting information content from a Web site by reading a designated Web page that
contains an XML (Extensible Markup Language) file that describes and includes the desired content. For example, REST could be used by an
online publisher to make syndicated content available. Periodically, the publisher would prepare and activate a Web page that included content
and XML statements that described the content. Subscribers would need only to know the URL (Uniform Resource Locator) for the page.

where the XML file was located, read it with a Web browser, interpret the content data using the XML information, and reformat and use it
appropriately (perhaps in some form of online publication).

As described in a dissertation by Roy Fielding, REST is an "architectural style" that basically exploits the existing technology and protocols
of the Web, including HTTP (Hypertext Transfer Protocol) and XML. REST is simpler to use than the well-known SOAP (Simple Object
Access Protocol) approach, which requires writing or using a provided server program (to serve data) and a client program (to request data).
SOAP, however, offers potentially more capability. For example, a syndicator that wanted to include up-to-date stock prices to subscribing
Web sites might need to use SOAP, which allows a greater amount of program interaction between client and server.

REST is consistent with an information publishing approach that a number of Web log sites use to describe some aspects of their site content,
called RDF Site Summary (RSS). RSS uses the Resource Description Framework (RDF), a standard way to describe a Web site or other
Internet resource.

i.e. Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web.
The term representational state transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation. Fielding is one of the
principal authors of the Hypertext Transfer Protocol (HTTP) specification versions 1.0 and 1.1.

The REST architectural style was developed in parallel with HTTP/1.1, based on the existing design of HTTP/1.0. The largest implementation of a system
conforming to the REST architectural style is the World Wide Web. REST exemplifies how the Web's architecture emerged by characterizing and
constraining the macro-interactions of the four components of the Web, namely origin servers, gateways, proxies and clients, without imposing limitations
on the individual participants. As such, REST essentially governs the proper behavior of participants .

REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate
responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and
meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of
a resource.The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are
outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time
the client chooses to initiate a new state transition. REST was initially described in the context of HTTP, but is not limited to that protocol.
RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for
applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-
defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-
specific features on top of it.

HTTP examples

HTTP, for example, has a very rich vocabulary in terms of verbs (or "methods"), URIs, Internet media types, request and response
codes, etc. REST uses these existing features of the HTTP protocol, and thus allows existing layered proxy and gateway
components to perform additional functions on the network such as HTTP caching and security enforcement.

SOAP RPC contrast

SOAP RPC over HTTP, on the other hand, encourages each application designer to define a new and arbitrary vocabulary of
nouns and verbs (for example getUsers(), savePurchaseOrder(...)), usually overlaid onto the HTTP POST verb. This disregards
many of HTTP's existing capabilities such as authentication, caching and content type negotiation, and may leave the application
designer re-inventing many of these features within the new vocabulary.[8] Examples of doing so may include the addition of
methods such as getNewUsersSince(Date date), savePurchaseOrder(string customerLogon, string password, ...)

The REST architectural style describes the following six constraints applied to the architecture, while leaving the implementation
of the individual components free to design:
Client–server Clients are separated from servers by a uniform interface. This separation of concerns means that, for example,
clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved.
Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients
may also be replaced and developed independently, as long as the interface is not altered.

Stateless The client–server communication is further constrained by no client context being stored on the server between requests.
Each request from any client contains all of the information necessary to service the request, and any session state is held in the
client. The server can be stateful; this constraint merely requires that server-side state be addressable by URL as a resource. This
not only makes servers more visible for monitoring, but also makes them more reliable in the face of partial network failures as
well as further enhancing their scalability.

Cacheable As on the World Wide Web, clients are able to cache responses. Responses must therefore, implicitly or explicitly,
define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data in response to further requests. Well-
managed caching partially or completely eliminates some client–server interactions, further improving scalability and

Layered system A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the
way. Intermediary servers may improve system scalability by enabling load balancing and by providing shared caches. They may
also enforce security policies.

Code on demand (optional) Servers are able to temporarily extend or customize the functionality of a client by transferring logic
to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as

Uniform interface The uniform interface between clients and servers, discussed below, simplifies and decouples the architecture,
which enables each part to evolve independently. The four guiding principles of this interface are detailed below. The only
optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred
to as RESTful. Complying with these constraints, and thus conforming to the REST architectural style, will enable any kind of
distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability,
visibility, portability and reliability.
                                                          Guiding principles of the interface
The uniform interface that any REST interface must provide is considered fundamental to the design of any REST service.

Identification of resources Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves
are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, perhaps, some
HTML, XML or JSON that represents some database records expressed, for instance, in Finnish and encoded in UTF-8, depending on the details of the
request and the server implementation.

Manipulation of resources through these representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server,
provided it has permission to do so.

Self-descriptive messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet
media type (previously known as a MIME type). Responses also explicitly indicate their cache ability.

Hypermedia as the engine of application state

Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g. by hyperlinks within hypertext).
Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources
beyond those described in representations previously received from the server

                                                                        Key goals
Key goals of REST include:

        Scalability of component interactions
        Generality of interfaces
        Independent deployment of components
        Intermediary components to reduce latency, enforce security and encapsulate legacy systems

REST has been applied to describe the desired web architecture, to help identify existing problems, to compare alternative solutions, and to
ensure that protocol extensions would not violate the core constraints that make the Web successful.
Fielding describes REST's effect on scalability thus:

REST's client–server separation of concerns simplifies component implementation, reduces the complexity of connector semantics, improves
the effectiveness of performance tuning, and increases the scalability of pure server components. Layered system constraints allow
intermediaries—proxies, gateways, and firewalls—to be introduced at various points in the communication without changing the interfaces
between components, thus allowing them to assist in communication translation or improve performance via large-scale, shared caching.
REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard
methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.

                                                         Central principle
An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global
identifier (e.g., a URI in HTTP). In order to manipulate these resources, components of the network (user agents and origin servers)
communicate via a standardized interface (e.g., HTTP) and exchange representations of these resources (the actual documents conveying
the information). For example, a resource that represents a circle may accept and return a representation that specifies a center point and
radius, formatted in SVG, but may also accept and return a representation that specifies any three distinct points along the curve (since this
also uniquely identifies a circle) as a comma-separated list.

Any number of connectors (e.g., clients, servers, caches, tunnels, etc.) can mediate the request, but each does so without "seeing past" its
own request (referred to as "layering," another constraint of REST and a common principle in many other parts of information and
networking architecture). Thus, an application can interact with a resource by knowing two things: the identifier of the resource and the
action required—it does not need to know whether there are caches, proxies, gateways, firewalls, tunnels, or anything else between it and
the server actually holding the information. The application does, however, need to understand the format of the information
(representation) returned, which is typically an HTML, XML or JSON document of some kind, although it may be an image, plain text, or any
other content.

                                                        RESTful web services
A RESTful web service (also called a RESTful web API) is a simple web service implemented using HTTP and the principles of REST. It is a
collection of resources, with four defined aspects:
        the base URI for the web service, such as http://example.com/resources/
        the Internet media type of the data supported by the web service. This is often JSON, XML or YAML but can be any other valid
         Internet media type.
        the set of operations supported by the web service using HTTP methods (e.g., POST, GET, PUT or DELETE).
        The API must be hypertext driven

                                                       Key REST principles
Most introductions to REST start with the formal definition and background. I’ll defer this for a while and provide a simplified, pragmatic
definition: REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used (which often differs
quite a bit from what many people actually do). The promise is that if you adhere to REST principles while designing your application, you
will end up with a system that exploits the Web’s architecture to your benefit. In summary, the five key principles are:

    1.   Give every “thing” an ID
    2.   Link things together
    3.   Use standard methods
    4.   Resources with multiple representations
    5.   Communicate statelessly

    1 Give every “thing” an ID: there is usually a set of key abstractions that merit being identified. Everything that should be identifiable
    should obviously get an ID — on the Web, there is a unified concept for IDs: The URI. URIs make up a global namespace, and using URIs
    to identify your key resources means they get a unique, global ID. The main benefit of a consistent naming scheme for things is
    that you don’t have to come up with your own scheme — you can rely on one that has already been defined, works pretty
    well on global scale and is understood by practically anybody. Some examples of URIs: :


2 Link things together: Consider the following made-up XML fragment:
    <order self='http://example.com/customers/1234' >

     <product ref='http://example.com/products/4554' />

     <customer ref='http://example.com/customers/1234' />


If you look at the product and customer links in this document, you can easily imagine how an application that has retrieved it can “follow”
the links to retrieve more information. Of course, this would be the case if there were a simple “id” attribute adhering to some application-
specific naming scheme, too — but only within the application’s context. The beauty of the link approach using URIs is that the links can
point to resources that are provided by a different application, a different server, or even a different company on another continent —
because the naming scheme is a global standard, all of the resources that make up the Web can be linked to each other

3 Use standard methods: the set of standard methods includes GET,POST, PUT, DELETE, HEAD and OPTIONS. The meaning of these
methods is defined in the HTTP specification, along with some guarantees about their behavior. If you are an OO developer, you can imagine
that every resource in a RESTful HTTP scenario extends a class like this (in some Java/C#-style pseudo-syntax and concentrating on the key

class Resource {

  Resource(URI u); Response get();

Response post(Request r); Response put(Request r); Response delete(); }
Because the same interface is used for every resource, you can rely on being able to retrieve a representation — i.e., some rendering of it —
using GET. Because GET’s semantics are defined in the specification. you can be sure that you have no obligations when you call it — this is
why the method is called “safe”.

4 Resources with multiple representations: a client that knows how to handle a particular data format can interact with all
resources that can provide a representation in this format. Let’s illustrate this with an example again. Using HTTP content negotiation, a
client can ask for a representation in a particular format:

GET /customers/1234 HTTP/1.1

Host: example.com

Accept: application/vnd.mycompany.customer+xml

The result might be some company-specific XML format that represents customer information. If the client sends a different request, e.g.
one like this:

GET /customers/1234 HTTP/1.1

Host: example.com

Accept: text/x-vcard

The result could be the customer address in VCard format. (I have not shown the responses, which would contain metadata about the type
of data in the HTTP Content-type header.) This illustrates why ideally, the representations of a resource should be in standard formats — if a
client “knows” both the HTTP application protocol and a set of data formats, it can interact with any RESTful HTTP application in the world in
a very meaningful way.

5 Communicate statelessly: First of all, it’s important to stress that although REST includes the idea of statelessness, this does not
mean that an application that exposes its functionally cannot have state — in fact, this would render the whole approach pretty useless in
most scenarios. REST mandates that state be either turned into resource state, or kept on the client. In other words, a server should not
have to retain some sort of communication state for any of the clients it communicates with beyond a single request. The most obvious
reason for this is scalability — the number of clients interacting would seriously impact the server’s footprint if it had to keep client state.
(Note that this usually requires some re-design — you can’t simply stick a URI to some session state and call it RESTful.) But there are other
aspects that might be much more important: The statelessness constraint isolates the client against changes on the server as it is not
dependent on talking to the same server in two consecutive requests. A client could receive a document containing links from the server,
and while it does some processing, the server could be shut down, its hard disk could be ripped out and be replaced, the software could be
updated and restarted — and if the client follows one of the links it has received from the server, it won’t notice.

REST - An Architectural Style, Not a Standard
REST is not a standard. You will not see the W3C putting out a REST specification. You will not see IBM or Microsoft or Sun selling a REST
developer's toolkit. Why? Because REST is just an architectural style. You can't bottle up that style. You can only understand it, and design
your Web services in that style. (Analogous to the client-server architectural style. There is no client-server standard.) While REST is not a
standard, it does use standards:

       HTTP
       URL
       XML/HTML/GIF/JPEG/etc (Resource Representations)
       text/xml, text/html, image/gif, image/jpeg, etc (MIME Types)

                                                         REST vs SOAP Web Services
What is a REST Web Service

The acronym REST stands for Representational State Transfer, this basically means that each unique URL is a representation of some object. You can get
the contents of that object using an HTTP GET, to delete it, you then might use a POST, PUT, or DELETE to modify the object (in practice most of the
services use a POST for this).

Who's using REST?
All of Yahoo's web services use REST, including Flickr, del.icio.us API uses it, pubsub, bloglines, technorati, and both eBay, and Amazon have web services
for both REST and SOAP.

Who's using SOAP?

Google seams to be consistent in implementing their web services to use SOAP, with the exception of Blogger, which uses XML-RPC. You will find SOAP
web services in lots of enterprise software as well.

REST vs SOAP As you may have noticed the companies that are using REST api's haven't been around for very long, and their apis came out this year
mostly. So REST is definitely the trendy way to create a web service, if creating web services could ever be trendy (lets face it you use soap to wash, and
you rest when your tired). T

the main advantages of REST web services are:

        Lightweight - not a lot of extra xml markup
        Human Readable Results
        Easy to build - no toolkits required

SOAP also has some advantages:

        Easy to consume – sometimes
        Rigid - type checking, adheres to a contract
        Development tools

For consuming web services, its sometimes a toss up between which is easier. For instance Google's AdWords web service is really hard to consume (in CF
anyways), it uses SOAP headers, and a number of other things that make it kind of difficult. On the converse, Amazon's REST web service can sometimes
be tricky to parse because it can be highly nested, and the result schema can vary quite a bit based on what you search for.Whichever architecture you
choose make sure its easy for developers to access it, and well documented,.

                                                  WS-* vs. RESTful Service
     WS-* Middleware Interoperability Standard
     REST Architectural style for the Web
Architectural Decisions
    Architectural decisions capture the main design issues and the rationale behind a chosen technical solution
    The choice between REST vs. WS-* is an important architectural decision for Web service design
    Architectural decisions affect one another
    21 Decisions and 64 alternatives Classified by level of abstraction:
                     3 Architectural Principles
                     9 Conceptual Decisions
                     9 Technology-level Decisions
Decisions help us to measure the complexity implied by the choice of REST or WS-*

Comparison Overview
                                 Protocol LayeringHTTP = Application-level Protocol (REST)
                                 HTTP = Transport-level Protocol (WS-*)
                                 Loose Coupling
                                 Dealing with Heterogeneity
                                 What about X? (X = Composition)
                                 Software Connectors for Integration
Coupling Facets
                                       Shared Model

    Generated Code

                                                                        Coupling Comparison

     Claim: REST can also be successfully used to design integrated enterprise applications]
     CRUD Services Web-friendly APIs Mobile Services
     Real-time Services Transactional Services Composite Services
     Part of the debate is about how many “enterprise” use cases can be covered with REST as opposed to

To top