Rest and SOAP API

Web Services

Web Services are the key point of Integration for different applications belonging to different Platforms, Languages, systems

The two primary architectures for APIs are REST and SOAP. When creating your API, you really have three options: REST, SOAP, or both.

REST APIs are known for being easy and quick to develop for, but the entire request is sent in the clear regardless of the type of encryption used.

SOAP APIs are more complex, requiring more effort to generate the response and handle the request, but allow for greater flexibility by adding namespace #Slide 20 support.

Providing APIs of both types may sound like an attractive option, but keep in mind that it will double your maintenance, support, and documentation time for the life of the API.

What is SOAP?

SOAP stands for Simple Object Access Protocol

SOAP is a communication protocol

SOAP is for communication between applications

SOAP is a format for sending messages

SOAP communicates via Internet

SOAP is platform independent

SOAP is language independent

SOAP is based on XML

SOAP allows you to get around firewalls

SOAP is a W3C recommendation

Why SOAP?

It is important for application development to allow Internet communication between programs.

Today's applications communicate using Remote Procedure Calls (RPC) , but HTTP was not designed for this. RPC represents a compatibility and security problem; firewalls and proxy servers will normally block this kind of traffic.

A better way to communicate between applications is over HTTP, because HTTP is supported by all Internet browsers and servers. SOAP was created to accomplish this.

SOAP provides a way to communicate between applications running on different operating systems, with different technologies and programming languages.

SOAP Building Blocks

A SOAP message is an ordinary XML document containing the following elements:

An Envelope element that identifies the XML document as a SOAP messageA Header element that contains header informationA Body element that contains call and response informationA Fault element containing errors and status information

Syntax

A SOAP message MUST be encoded using XMLA SOAP message MUST use the SOAP Envelope namespaceA SOAP message MUST use the SOAP Encoding namespace

<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>...</soap:Header>

<soap:Body>... <soap:Fault> ... </soap:Fault></soap:Body>

</soap:Envelope>

In the example below, a GetStockPrice request is sent to a server. The request has a StockName parameter, and a Price parameter that will be returned in the response. The namespace for the function is defined in "http://www.example.org/stock".

SOAP Request

POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock"> <m:GetStockPrice> <m:StockName>IBM</m:StockName> </m:GetStockPrice></soap:Body></soap:Envelope>

SOAP Response

HTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn

<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock"> <m:GetStockPriceResponse> <m:Price>34.5</m:Price> </m:GetStockPriceResponse></soap:Body>

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 .

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines

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

Rest Services are:-

Platform-independent (you don't care if the server is Unix, the client is a Mac, or anything else),

Language-independent (C# can talk to Java, etc.),

Standards-based (runs on top of HTTP), and

Can easily be used in the presence of firewalls.

One thing that is not part of a good REST design is cookies: The "ST" in "REST" stands for "State Transfer", and indeed, in a good REST design operations are self-contained, and each request carries with it (transfers) all the information (state) that the server needs in order to complete it.

Using Web Services and SOAP, the request would look something like this:

<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:body pb="http://www.acme.com/phonebook"> <pb:GetUserDetails> <pb:UserID>12345</pb:UserID> </pb:GetUserDetails> </soap:Body></soap:Envelope>And with REST? The query will probably look like this:

http://www.acme.com/phonebook/UserDetails/12345REST can easily handle more complex requests, including multiple parameters. In most cases, you'll just use HTTP GET parameters in the URL.

http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe

Rest Server Response

<parts-list> <part id="3322"> <name>ACME Boomerang</name> <desc> Used by Coyote in <i>Zoom at the Top</i>, 1962 </desc> <price currency="usd" quantity="1">17.32</price> <uri>http://www.acme.com/parts/3322</uri> </part> <part id="783"> <name>ACME Dehydrated Boulders</name> <desc> Used by Coyote in <i>Scrambled Aches</i>, 1957 </desc> <price currency="usd" quantity="pack">19.95</price> <uri>http://www.acme.com/parts/783</uri> </part></parts-list>

However, other formats can also be used; unlike SOAP services, REST is not bound to XML in any way. Possible formats include CSV (comma-separated values) and JSON (JavaScript Object Notation).

Here's a simple example: the following URL sends a REST request to Yahoo!'s web-search service: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=rest. Click it, and observe the XML results, ready to be used directly, not wrapped in an SOAP "envelope" or other noise.

AJAX and Rest

AJAX is a popular web development technique that makes web pages interactive using JavaScript.

In AJAX, requests are sent to the server using XMLHttpRequest objects. The response is used by the JavaScript code to dynamically change the current page.

In many ways, AJAX applications follow the REST design principles. Each XMLHttpRequest can be viewed as a REST service request, sent using GET. And the response is often in JSON, a popular response format for REST. (See REST Server Responses, above.)

To make your AJAX application truly RESTful, follow the standard REST design principles

REST architecture

Key components of a REST architecture:

Resources, which are identified by logical URLs. Both state and

functionality are represented using resources.

The logical URLs imply that the resources are universally

addressable by other parts of the system.

Resources are the key element of a true RESTful design, as

opposed to "methods" or "services" used in RPC and SOAP Web

Services, respectively. You do not issue a "getProductName" and

then a "getProductPrice" RPC calls in REST; rather, you view the

product data as a resource -- and this resource should contain all the

required information (or links to it).

...

A web of resources, meaning that a single resource should not be

overwhelmingly large and contain too fine-grained details. Whenever relevant, a

resource should contain links to additional information -- just as in web pages.

The system has a client-server, but of course one component's server can be

another component's client.

There is no connection state; interaction is stateless (although the servers and

resources can of course be stateful). Each new request should carry all the

information required to complete it, and must not rely on previous interactions

with the same client.

REST Design Guidelines

Do not use "physical" URLs. A physical URL points at something physical -- e.g., an XML file: "http://www.acme.com/inventory/product003.xml". A logical URL does not imply a physical file: "http://www.acme.com/inventory/product/003".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.

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 n products (e.g., the first 10), with next/prev links.

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.

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).

REST vs SOAP

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). The main

Advantages of REST web services are:

Lightweight - not a lot of extra xml markupHuman Readable ResultsEasy to build - no toolkits required

SOAP also has some advantages:

Easy to consume - sometimesRigid - type checking, adheres to a contractDevelopment tools

In general, a namespace uniquely identifies a set of names so that there is no ambiguity when objects having different origins but the same names are mixed together. Using the Extensible Markup Language (XML), an XML namespace is a collection of element type and attribute names. These element types and attribute names are uniquely identified by the name of the unique XML namespace of which they are a part.

#Slide 2