RESTful Web Services

1. Message Oriented Communication and Resource Oriented Communication

➤ Message Oriented Communication

• Message-oriented communication is a way of communicating between processes. 
• Messages, which correspond to events, are the basic units of data delivered. 
• Tanenbaum and Steen classified message-oriented communication according to two factors synchronous or asynchronous communication, and transient or persistent communication. 
• In synchronous communication, the sender blocks waiting for the receiver to engage in the exchange. 
• Asynchronous communication does not require both the sender and the receiver to execute simultaneously. 
• So, the sender and recipient are loosely-coupled. 
• The amount of time messages are stored determines whether the communication is transient or persistent. 
• Transient communication stores the message only while both partners in the communication are executing. 
• If the next router or receiver is not available, then the message is discarded. 
• Persistent communication, on the other hand, stores the message until the recipient receives it.

➤ Resource Oriented Communication

• Resource oriented communication is a communication  that aims to exploit the low-level communication facilities of today’s cluster networking hardware and to merge, via the resource oriented paradigm, those facilities and the high-level degree of parallelism achieved on SMP systems through multi-threading. 
• The communication model defines three major entities – contexts, resources and buffers – which permit the design of high-level solutions. 
• A low-level distributed directory is used to support resource registering and discovering. 
• The usefulness and applicability of RoCL is briefly addressed through a basic modelling example – the implementation of TPVM over RoCL.
•  Performance results for Myrinet and Gigabit Ethernet, currently supported in RoCL through GM and MVIA, respectively, are also presented.

2. The Resource Based Nature of The REST Style

• The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. It is similar to an object instance in an object-oriented programming language, with the important difference that only a few standard methods are defined for the resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods), while an object instance typically has many methods.

• Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource, and unordered. Resources can also exist outside any collection. In this case, we refer to these resources as singleton resources. Collections are themselves resources as well.

• Collections can exist globally, at the top level of an API, but can also be contained inside a single resource. In the latter case, we refer to these collections as sub-collections. Sub-collections are usually used to express some kind of “contained in” relationship. We go into more detail on this in relationships.

• Resources have data associated with them. The richness of data that can be associated with a resource is part of the resource model for an API. It defines for example the available data types and their behavior.

• A RESTful approach to software development can greatly simplify the task of application integration, but this new approach can often cause troubles for those with more of a legacy background in distributed computing. That’s when developers finds themselves creating more problems than they fix. Louvel’s advice is not to take the usual, traditional approach when developing RESTful APIs. Forget what you learned from the service-oriented, RPC based world. Then, you’ll discover that you are working without limitations and you can really start to solve your business problems. Furthermore, the modularity involved in developing a RESTful architecture means developers have smaller, more agile parts that provide greater flexibility when designing solutions that really work.

3. Representations in REST Style

• Representation is the value/response of the Resource at a point in time based on the media-type. 
• Resources can be manipulated only through their representations.
• This is exactly how browsing the web works. An HTML page is not a resource, it’s just one representation. 
• And when we submit a form, we’re just sending a different representation back to the server.
• One resource could have many representations. Heck, you could get crazy and have an API where you’re able to request the XML, JSON or HTML representations of any resource. 
• We’re just crazy enough that we’ll do some of that.
• A representation is a machine readable explanation of the current state of a resource.
• In REST-speak, a client and server exchange representations of a resource, which reflect its current state or its desired state. 
• REST, or Representational state transfer, is a way for two machines to transfer the state of a resource via representations.

4. Constraints of REST

• REST stands for Representational State Transfer, a term coined by Roy Fielding in 2000. It is an architecture style for designing loosely coupled applications over HTTP, that is often used in the development of web services. REST does not enforce any rule regarding how it should be implemented at lower level, it just put high level design guidelines and leave you to think of your own implementation.
• REST defines 6 architectural constraints which make any web service – a true RESTful API.

➤ Uniform Interface

• As the constraint name itself applies, you MUST decide APIs interface for resources inside the system which are exposed to API consumers and follow religiously. A resource in the system should have only one logical URI and that should provide a way to fetch related or additional data. It’s always better to synonymise a resource with a web page.

• Any single resource should not be too large and contain each and everything in its representation. Whenever relevant, a resource should contain links (HATEOAS) pointing to relative URIs to fetch related information.

• Also, the resource representations across system should follow certain guidelines such as naming conventions, link formats or data format (xml or/and json).

• All resources should be accessible through a common approach such as HTTP GET and similarly modified using a consistent approach.

➤ Client-Server

• This essentially means that client application and server application MUST be able to evolve separately without any dependency on each other. A client should know only resource URIs and that’s all. Today, this is normal practice in web development so nothing fancy is required from your side. Keep it simple.

➤ Stateless

• Roy fielding got inspiration from HTTP, so it reflects in this constraint. Make all client-server interaction stateless. Server will not store anything about latest HTTP request client made. It will treat each and every request as new. No session, no history.

• If client application needs to be a stateful application for the end user, where user logs in once and do other authorized operations thereafter, then each request from the client should contain all the information necessary to service the request – including authentication and authorization details.

➤ Cacheable

• In today’s world, caching of data and responses is of utmost important wherever they are applicable/possible. The webpage you are reading here is also a cached version of the HTML page. Caching brings performance improvement for client side, and better scope for scalability for a server because the load has reduced.

• In REST, caching shall be applied to resources when applicable and then these resources MUST declare themselves cacheable. Caching can be implemented on the server or client side.

➤ Layered System

• REST allows you to use a layered system architecture where you deploy the APIs on server A, and store data on server B and authenticate requests in Server C, for example. A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.

➤ Code On Demand

• Well, this constraint is optional. Most of the time you will be sending the static representations of resources in form of XML or JSON. But when you need to, you are free to return executable code to support a part of your application e.g. clients may call your API to get a UI widget rendering code. It is permitted.

5. Different Types of Implementations For The Elements of REST Style

• The key aspect of REST is the state of the data elements, its components communicate by transferring representations of the current or desired state of data elements. REST identifies six data elements: a resource, resource identifier, resource metadata, representation, representation metadata, and control data, shown in the table below

➤ Resource Element

• Any information that can be named is a resource. A resource is a conceptual mapping to a set of entities not the entity itself. Such a mapping can change over time. In general, a RESTful resource is anything that is addressable over the Web.

• Example -- Title of a movie from IMDb, A Flash movie from YouTube, Images from Flickr etc
  

➤ Resource Identifier Element

• Every resource must have a name that uniquely identifies it. Under HTTP these are called URIs. Uniform Resource Identifier (URI) in a RESTful system is a hyperlink to a resource. It is the only means for clients and servers to exchange representations of resources.The relationship between URIs and resources is many to one. A resource can have multiple URIs which provide different information about the location of a resource.
  

• Example -- Standardized format of URI:scheme://host:port/path?queryString#fragmente.g:http://some.domain.com/orderinfo?id=123

➤ Resource Metadata

• This describes the resource. A metadata provides additional information such as location information, alternate resource identifiers for different formats or entity tag information about the resource itself.
  

• Example --Source link, vary

➤ Representation

• It is something that is sent back and forth between clients and servers. So, we never send or receive resources, only their representations. A representation captures the current or intended state of a resource. A particular resource may have multiple representations.
  

• Example -- Sequence of bytes, HTML document, archive document, image document.
  

➤ Control Data

• This defines the purpose of a message between components, such as the action being requested.
  

• Example -- If-Modified-Since, If-Match

6. How to Define the API of RESTful Web Services Using RESTful URLs

• REST is used to build Web services that are lightweight, maintainable, and scalable in nature. A service which is built on the REST architecture is called a RESTful service. The underlying protocol for REST is HTTP, which is the basic web protocol.

• A RESTful API breaks down a transaction to create a series of small modules. Each module addresses a particular underlying part of the transaction. This modularity provides developers with a lot of flexibility, but it can be challenging for developers to design from scratch. Currently, the models provided by Amazon Simple Storage Service, Cloud Data Management Interface and OpenStack Swift are the most popular.

• A RESTful API explicitly takes advantage of HTTP methodologies defined by the RFC 2616 protocol. They use GET to retrieve a resource; PUT to change the state of or update a resource, which can be an object, file or block; POST to create that resource ; and DELETE to remove it.

• Under REST principles, a URL identifies a resource. The following URL design patterns are considered REST best practices:

1. URLs should include nouns, not verbs.
2. Use plural nouns only for consistency (no singular nouns).
3. Use HTTP methods (HTTP/1.1) to operate on these resources:
4. Use HTTP response status codes to represent the outcome of operations on resources.

➤ URL Depth

• The resource/identifier/resource URL pattern is sufficient for full attribute visibility between any resources. Therefor, this URL depth is usually sufficient to support any arbitrary resource graph. If your URL design goes deeper than resource/identifier/resource, it may be evidence that the granularity of your API is too coarse.

➤ API Payload Format Encoding

• To interact with an API, the consumer needs to know how the payload is encoded. This is true regardless of how many encoding formats the endpoint supports.

• The three patterns of payload format encoding most frequently found in the wild are:

1. HTTP headers (e.g. Content-Type: and Accept:)
2. GET parameters (e.g. &format=json)
3. resource label (e.g. /foo.json)

• Using HTTP headers to specifying payload format can be convenient, however unfortunately not all clients handle headers consistently. Using HTTP headers alone will create issues for buggy clients.

• Using GET parameters to specify format is another common pattern for specifying the encoding of API payloads. This results in slightly longer URLs than resource label technique, and can occasionally create problems with caching behavior of some proxy servers.

• Resource label specification of API payload format, such as /foo/{id}.json, are functionally equivalent to GET parameter encoding but without the (admittedly rare) proxy caching issues.

8. JAX-RS API

• JAX-RS is a Java API for RESTful Web Services (JAX-RS) is a Java programming language API spec that provides support in creating web services according to the Representational State Transfer (REST) architectural pattern. JAX-RS uses annotations, introduced in Java SE 5, to simplify the development and deployment of web service clients and endpoints.

• From version 1.1 on, JAX-RS is an official part of Java EE 6. A notable feature of being an official part of Java EE is that no configurations is necessary to start using JAX-RS. For non Java EE 6 environments a small entry in the web . xml deployment descriptoris required.

➤ Implementations

• Apache CXF, an open source Web service framework
• Jersey, the reference implementation from Sun (now Oracle)
• WebSphere Application Server from IBM
• WebLogic Application Server from Oracle
• Cuubez framework
• Codenvy's Implementation
• Java Application Framework optimized for Google App Engine, including a powerful RESTful engine and comprehensive Data Authorization model

9. Annotations in JAX-RS

➤ Path

• It identifies the URI path. It can be specified on class or method.

➤ PathParam

• Represents the parameter of the URI path.

➤ GET

• specifies method responds to GET request.

➤ POST

• specifies method responds to POST request.

➤ PUT

• specifies method responds to PUT request.

➤ HEAD

• specifies method responds to HEAD request.

➤ QueryParam

• represents the parameter of the query string of an URL.

➤ Produces

• defines media type for the response such as XML, PLAIN, JSON etc. It defines the media type that the methods of a resource class or MessageBodyWriter can produce.

➤ Consumes

• It defines the media type that the methods of a resource class or MessageBodyReader can produce.

➤ CookieParam

• represents the parameter of the cookie.

➤ FormParam

• represents the parameter of the form.

➤ OPTIONS

• specifies method responds to OPTIONS request.

10. Media Type in JAX-RS

• All resource methods can consume and produce content of almost any type. If you make a POST request to a URI, such as api/books , the REST API expects the HTTP body to contain a payload that represents the resource it should create.
• This resource can be represented using any media type. Although typically, it will be represented in either, JSON or XML ,    but ut could be plain text , binary or a custom format. It doesn't matter , as long as there is a method in the resource class that can consume that media type.

➤ javax.ws.rs.core

• Low-level interfaces and annotations used to create RESTful service resources.

➤ javax.ws.rs.ext

• APIs that provide extensions to the types supported by the JAX-RS API

Web Services And Soap

1. Web Applications And Web Services

➤ Web Applications

• A web application is a software application that runs on a remote server. 
• In most cases, Web browsers are used to access Web applications, over a network, such as the Internet. 
• Some web applications are used in intranets, in companies and schools, for example. 
• Web applications are different from other applications because they do not need to be installed.
• Some example web applications are: Facebook (social networking), Flickr (photo sharing), Mibbit (chatting), and Wikipedia.
• Web applications are popular because most computer operating systems have web browsers.
• Programmers can easily change a web application. 
• Users do not need to install any new software to see these changes.

➤ Benefits

1. Web applications run "inside" a browser; no complex installation is needed.
2. Web applications require very little disk space (or computing power) on the client. All the client does is display the data.
3. In many cases, the data is stored remotely too. As with other cloud computing, this can allow easy communication and cooperation.
4. Web applications solve some of the "compatibility issues" (Windows, Mac, Linux); all that is needed is a browser.
5. Help for communication and mail.

➤ Web Services

• A web service is any piece of software that makes itself available over the internet and uses a standardized XML messaging system. 
• XML is used to encode all communications to a web service. 
• For example, a client invokes a web service by sending an XML message, then waits for a corresponding XML response. 
• As all communication is in XML, web services are not tied to any one operating system or programming language—Java can talk with Perl; Windows applications can talk with Unix applications.
• Web services are self-contained, modular, distributed, dynamic applications that can be described, published, located, or invoked over the network to create products, processes, and supply chains. 
• These applications can be local, distributed, or web-based. Web services are built on top of open standards such as TCP/IP, HTTP, Java, HTML, and XML.
• Web services are XML-based information exchange systems that use the Internet for direct application-to-application interaction. 
• These systems can include programs, objects, messages, or documents.

➤ Why We Need Web Services?

• A web service is a unit of managed code that can be remotely invoked using HTTP. That is, it can be activated using HTTP requests. Web services allow you to expose the functionality of your existing code over the network. Once it is exposed on the network, other applications can use the functionality of your program.

➤ Interoperability

• Web services allow various applications to talk to each other and share data and services among themselves. 
• Other applications can also use the web services. 
• For example, a VB or .NET application can talk to Java web services and vice versa. 
• Web services are used to make the application platform and technology independent.

➤ Standardized Protocol

• Web services use a standardized industry standard protocol for the communication. 
• All the four layers (Service Transport, XML Messaging, Service Description, and Service Discovery layers) use well-defined protocols in the web services protocol stack. 
• This standardization of protocol stack gives the business many advantages such as a wide range of choices, reduction in the cost due to competition, and increase in the quality.

➤ Low Cost Communication

• Web services use SOAP over HTTP protocol, so you can use your existing low-cost internet for implementing web services. 
• This solution is much less costly compared to proprietary solutions like EDI/B2B. 
• Besides SOAP over HTTP, web services can also be implemented on other reliable transport mechanisms like FTP.

➤ Web Applcations Vs. Web Services

Web Service	Web Application
A web service doesn't have a user interface	A web application has a user interface or GUI
Web services are meant for other applications to be interacted with over internet	Web applications are meant for use by humans
Web services are platform independent as they use open protocols	Web applications are cross platform as they require tweaking to operate on different browsers, operating systems etc.
Web services are accessed by HTTP methods - GET, POST, PUT, DELETE etc	Web applications are accessed by using their GUI components - buttons, text boxes, forms etc
E.g. Google maps API is a web service that can be used by websites to display Maps by passing coordinates to it	E.g. ArtOfTesting.com is web application that has collection of related web pages containing tutorials

---

2.Web Service Definition Language

• WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. 
• The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). 
• WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

➤ Features

1. WSDL is an XML-based protocol for information exchange in decentralized and distributed environments.
2. WSDL definitions describe how to access a web service and what operations it will perform.
3. WSDL is a language for describing how to interface with XML-based services.
4. WSDL is an integral part of Universal Description, Discovery, and Integration (UDDI), an XML-based worldwide business registry.
5. WSDL is the language that UDDI uses.
6. WSDL is pronounced as 'wiz-dull' and spelled out as 'W-S-D-L'.

➤ Usage

• WSDL is often used in combination with SOAP and XML Schema to provide web services over the Internet. 
• A client program connecting to a web service can read the WSDL to determine what functions are available on the server. 
• Any special datatypes used are embedded in the WSDL file in the form of XML Schema. 
• The client can then use SOAP to actually call one of the functions listed in the WSDL.

• The WSDL describes services as collections of network endpoints, or ports. The WSDL specification provides an XML format for documents for this purpose. The abstract definitions of ports and messages are separated from their concrete use or instance, allowing the reuse of these definitions. A port is defined by associating a network address with a reusable binding, and a collection of ports defines a service. Messages are abstract descriptions of the data being exchanged, and port types are abstract collections of supported operations. The concrete protocol and data format specifications for a particular port type constitutes a reusable binding, where the operations and messages are then bound to a concrete network protocol and message format. In this way, WSDL describes the public interface to the Web service.

• WSDL is often used in combination with SOAP and an XML Schema to provide Web services over the Internet. A client program connecting to a Web service can read the WSDL file to determine what operations are available on the server. Any special datatypes used are embedded in the WSDL file in the form of XML Schema. The client can then use SOAP to actually call one of the operations listed in the WSDL file using for example XML over HTTP.

---

3. WSDL Document

• A WSDL document has various elements, but they are contained within these three main elements, which can be developed as separate documents and then they can be combined or reused to form complete WSDL files.
• A WSDL document contains the following elements 

➤ Definition

• It is the root element of all WSDL documents. 
• It defines the name of the web service, declares multiple namespaces used throughout the remainder of the document, and contains all the service elements described here.

➤ Data Types

• The data types to be used in the messages are in the form of XML schemas.

➤ Message

• It is an abstract definition of the data, in the form of a message presented either as an entire document or as arguments to be mapped to a method invocation.

➤ Operation

• It is the abstract definition of the operation for a message, such as naming a method, message queue, or business process, that will accept and process the message.

➤ Port Type

• It is an abstract set of operations mapped to one or more end-points, defining the collection of operations for a binding; the collection of operations, as it is abstract, can be mapped to multiple transports through various bindings.

➤ Binding

• It is the concrete protocol and data formats for the operations and messages defined for a particular port type.

➤ Port

•  It is a combination of a binding and a network address, providing the target address of the service communication.

➤ Service

• It is a collection of related end-points encompassing the service definitions in the file; the services map the binding to the port and include any extensibility definitions.

• A WSDL document describes a service, its location, its operations, and the way in which clients can communicate with it. 
• This section provides a very brief introduction to WSDL, to provide context for discussing Service Bus features.
• WSDL specifies SOAP, HTTP, MIME, and Service Bus-specific binding extensions, which extend the WSDL binding mechanism to support features specific to the protocol or message format.
• In Service Bus, a WSDL document describes a proxy or business service, pipeline, or split-join. 
• You can base SOAP and XML services on an existing WSDL resource. 
• Service Bus defines some types of business services, proxy services. and pipelines using a WSDL document, an XML-based specification for describing web services. 
• All split-joins are based on a WSDL document. A WSDL document describes service operations, input and output parameters, and how a client application connects to the service. 
• For the WSDL 1.1 specification, see the W3C Note, "W3C Web Services Description Language (WSDL)
• In Service Bus, you can base a new service on an existing WSDL file (called a WSDL resource) and then override or add configuration properties. In the runtime, Service Bus generates an effective WSDL document for the service that includes the configuration of the WSDL resource along with additional transport and runtime configuration.

➤ Effective WSDL Documents

• For WSDL-based services, Service Bus uses effective WSDL documents in the runtime instead of the actual .wsdl files you create when you develop Service Bus services. 
• The effective WSDL document represents a service's WSDL properties as configured in Service Bus and also includes additional properties configured outside of the source WSDL document. The source WSDL document serves as a template for the effective WSDL document.
• When you create a service based on a WSDL document, Service Bus generates an effective WSDL document at runtime by combining properties from the original WSDL document, any transport properties you configured, runtime settings (like the target server), and any WS-Policy configurations. 
• Any properties you add or change from the original WSDL document during runtime are included in the effective WSDL document. Properties from the source WSDL document that are not used in the new configuration are omitted from the effective WSDL document.
• Service Bus can generate effective WSDL documents for SOAP and XML services that are created from a WSDL document and that use any transport that supports WSDL-based services, such as HTTP, JMS, SB, and so on. Service Bus cannot generate effective WSDL documents for services of the following types: Any SOAP, Any XML, and messaging.
• Effective WSDL documents have different characteristics for proxy services and business services and for services based on WSDL ports or on WSDL bindings. For more information, see Services Based on WSDL Ports and on WSDL Bindings.

➤ Generated WSDL Document

• A generated WSDL document is an effective WSDL document that Service Bus generates for transport-type services that were not created from a WSDL resource but that can be described using a WSDL document. 
• For example, you can generate a WSDL document from an EJB-based service.

➤ Structure Of WSDL Document

• Web Services Description Language (WSDL) is an XML grammar for describing network services as collections of communication endpoints capable of exchanging messages. The diagram below illustrates the elements that are present in a WSDL document, and indicates their relationships.

• A WSDL document has a definitions element that contains the other five elements, types, message, portType, binding and service. 
• The following sections describe the features of the generated client code.
• WSDL supports the XML Schemas specification (XSD) as its type system.

➤ Definitions

• Contains the definition of one or more services. JDeveloper generates the following attribute declarations for this section:

• Name is optional.
• Targetnamespace is  is the logical namespace for information about this service. WSDL documents can import other WSDL documents, and setting targetNamespace to a unique value ensures that the namespaces do not clash.
• xmlns is the default namespace of the WSDL document.
• All the WSDL elements such as <definitions> , <types> and <message> reside in this namespace.
• xmlns:xsd and xmlns:soap are standard namespace definitions that are used for specifying SOAP-specific information as well as data types.
• xmlns:tns stands for this namespace.
• xmlns:nsl is set to the value of the schema target nmespace in the <types> section.

---

5. Port Type and Operation Element

➤ PortType element

• The <portType> element combines multiple message elements to form a complete one-way or round-trip operation.
• For example, a <portType> can combine one request and one response message into a single request/response operation. 
• This is most commonly used in SOAP services. 
• A portType can define multiple operations.
• WSDL supports four basic patterns of operation.

➤ One-way

• The service receives a message. The service receives a message. The operation therefore has a single input element.

➤ Request-response

• The service receives a message and sends a response. 
• The operation therefore has one input element, followed by one output element. 
• To encapsulate errors, an optional fault element can also be specified.

➤ Solicit Response

• The service sends a message and receives a response. 
• The operation therefore has one output element, followed by one input element. 
• To encapsulate errors, an optional fault element can also be specified. 

➤Operation Element

• We can code 1 to 255 wsdl:operation elements as the child elements of the wsdl:binding element. 
• This element cannot be omitted. 
• If omitted or if 256 or more elements are coded, an error message (KDJW51029-E) is output to the standard error output and the log, and the processing of the cjwsimport command ends.
• You can specify the following elements as the child element. If you specify elements other than the following WSDL elements, an error message (KDJW51029-E) is output to the standard error output and the log, and the processing of the cjwsimport command ends. 
• Specify the child elements of the wsdl:operation element (for the child element of the wsdl:binding element) in the above order. 
• If the specification order is incorrect, an error message (KDJW51029-E) is output to the standard error output and the log, and the processing of the cjwsimport command ends.
• You can specify the name attribute. 
• You cannot specify attributes other than the name attribute. If you specify attributes other than the name attribute, an error message (KDJW51029-E) is output to the standard error output and the log, and the processing of the cjwsimport command ends.
• Define the wsdl:operation element of the wsdl:binding element so that it corresponds to the wsdl:operation element defined in the wsdl:portType element. 
• If the element is not defined in this manner, an error message (KDJW51112-E) is output to the standard error output and the log, and the processing of the cjwsimport command ends.
• When you specify the wsdl:output element as a child element, define the wsdl:output element so that it corresponds to the wsdl:output element defined in the wsdl:operation element of the wsdl:portType element.

---

6. Binding and Service Elements in WSDL

➤ Binding Element

• The <binding> element provides specific details on how a portType operation will actually be transmitted over the wire.
• The bindings can be made available via multiple transports including HTTP GET, HTTP POST, or SOAP.
• The bindings provide concrete information on what protocol is being used to transfer portType operations.
• The bindings provide information where the service is located.
• For SOAP protocol, the binding is <soap:binding>, and the transport is SOAP messages on top of HTTP protocol.
• The binding element has two attributes : name and type attribute.
• The name attribute defines the name of the binding, and the type attribute points to the port for the binding, in this case the "tns:Hello_PortType" port.

➤ Service Element

• The <service> element defines the ports supported by the web service. 
• For each of the supported protocols, there is one port element. 
• The service element is a collection of ports.
• Web service clients can learn the following from the service element

1.  where to access the service
2. through which port to access the web service
3. how the communications messages are defined.

• The service element includes a documentation element to provide human-readable documentation.
• The binding attributes of port element associate the address of the service with a binding element defined in the web service. 

---

7. How SOAP is Used With HTTP

• SOAP is an XML-based protocol for accessing web services over HTTP. 
• It has some specification which could be used across all applications.
• SOAP is known as the Simple Object Access Protocol, but in later times was just shortened to SOAP v1.2. 
• SOAP is a protocol or in other words is a definition of how web services talk to each other or talk to client applications that invoke them.
• SOAP was developed as an intermediate language so that applications built on various programming languages could talk easily to each other and avoid the extreme development effort.
• SOAP was designed to work with XML over HTTP and have some sort of specification which could be used across all applications.

• First of all SOAP defines a data encapsulation format and that's that.
• Now the majority of traffic in the web is via HTTP. 
• HTTP is literary EVERYWHERE and supported by a well-established infrastructure of servers and clients(namely browsers).
• Additionally it is a very well understood protocol.
• The tunneling over HTTP would and did help in it's rapid adoption. 
• Because the infrastructure of HTTP is already in-place, companies would not have to spend extra money for another kind of implementation. Instead they can expose and access web services using technology already deployed.
• Specifically in Java a web service can be deployed either as a servlet endpoint or as an EJB endpoint. So all the underlying network sockets, threads, streams, HTTP transactions etc. are handled by the container and the developer focuses only on the XML payload.
• So a company has Tomcat or JBoss running in port 80 and the web service is deployed and accessible as well. There is no effort to do programming at the transport layer and the robust container handles everything else.
• Finally the fact that firewalls are configured not to restrict HTTP traffic is a third reason to prefer HTTP.
• Since HTTP traffic is usually allowed, the communication of clients/servers is much easier and web services can function without network security blockers issues as a result of the HTTP tunneling.
• SOAP is XML=plain text so firewalls could inspect the content of HTTP body and block accordingly. But in this case they could also be enhanced to reject or accept SOAP depending on the contents.This part which seems to trouble you is not related to web services or SOAP, and perhaps you should start a new thread concerning how firewalls work.
• SOAP HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc.
• Whether to use the Extension Framework or plain HTTP is a question of policy and capability of the communicating parties. Clients can force the use of the HTTP Extension Framework by using a mandatory extension declaration and the "M-" HTTP method name prefix. Servers can force the use of the HTTP Extension Framework by using the 510 "Not Extended" HTTP status code. That is, using one extra round trip, either party can detect the policy of the other party and act accordingly.

---

8. How SOAP Can Be Used for Functional Oriented Communication?

• SOAP ( Simple Object Access Protocol) is a message protocol that allows distributed elements of an application to communicate. 
• SOAP can be carried over a variety of lower-level protocols, including the web-related Hypertext Transfer Protocol (HTTP).  
• SOAP defines a header structure that identifies the actions that various SOAP nodes are expected to take on the message, in addition to a payload structure for carrying information. 
• The concept of routing a message through a string of nodes that perform different functions is how SOAP supports things like addressing, security and format-independence. 
• Essentially, the headers identify roles, which in turn provide the SOA features which SOAP then routes to. 
• Stringing messages through a sequence of steps is uncommon in today’s microservice-centric development environments.
• A system for object oriented communication among platform independent systems over networks using SOAP, in which communications can be performed over the internet and through a firewall utilizing a single communications protocol. 
• A simple object access communications protocol (SOAP) is utilized for sending messages from one object to another across the internet in a platform independent manner. 
• This type of protocol can be utilized to control network elements provided at various locations.
• SOAP is a protocol that’s almost always used in the context of a Web Services/SOA framework.  
• As such, it’s application programming interface (API) is typically hidden by the higher-level interface for SOA. 
• There are SOA API middleware tools available for nearly all modern programming languages, and Microsoft offers a variety of .NET SOAP/SOA tools.
• All communication by SOAP is done via the HTTP protocol. 
• Prior to SOAP, a lot of web services used the standard RPC (Remote Procedure Call) style for communication. 
• This was the simplest type of communication, but it had a lot of limitations.

---

9. Structure of SOAP message

• In the previous articles, We have gone through basics of SOAP Webservice and Steps to create SOAP Webservice. 
• As we are knowing that SOAP forms message before communicating with Server, 
• That message called as a SOAP Message. 
• Today, We will understand in depth of SOAP Message and Structure of the message.
• A SOAP based web service message is a hierarchical XML packet, consisting of up to four parts.

1. Envelop
2. Header
3. Body
4. Fault

➤ The SOAP Envelop

• The SOAP <Envelope> is the root element in every SOAP message. 
• It contains two child elements, an optional <Header>, and a mandatory <Body>.
• The root element of the XML packet is called the envelope. 
• An envelope is a mandatory element in a SOAP Message. 
• It defines a namespace ending with soap dash envelope. 
• And associates it with a namespace prefix. The prefix can be anything. 
• In some examples, we have seen it named soap, in other others soapenv, or as in this example, just env. 
• What’s important, is that it points to the correct namespace, that identifies the version of SOAP that’s being used.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cod="http://codenuclear.com/">

   ...

   ...

</soapenv:Envelope>

➤ The SOAP Header

• The SOAP <Header> is an optional subelement of the SOAP envelope. 
• It is used to pass application-related information that is to be processed by SOAP nodes along the message path.
• The XML envelope, defines two child elements named header and body. 
• When we look at the schema [http://schemas.xmlsoap.org/soap/envelope/], We’ll see that there is an attribute called minoccurs, that indicates whether each is required. 
• Zero would mean optional, meaning there is no minimum, and one means required. 
• So, in a SOAP envelope, the header element is optional, but the body is required. 
• If the message contains a header, it shows up as the first child element of the Envelope.
• The header contains metadata, It can contain documentation about the particular soap message and any other elements a developer might like to include. 
• Some common uses of the soap header, include API keys, or log-in credentials to validate requests, or timestamps in responses indicating when data was created, or how long it’s good for.

<soapenv:Header>

<cod:username>Admin</cod:username>

<cod:password>xxxxx</cod:password>

<soapenv:Header/>

➤ The SOAP Body

• The SOAP <Body> is a mandatory subelement of the SOAP envelope. 
• It contains information intended for the ultimate recipient of the message.
• The body element is required in both the request and the response envelope And it contains the actual content of either the request or the response. 
• A request message typically defines a namespace that’s again unique to the web service being called.
• The child element in the body, getStockPrice, is the name of a remote procedure that’s defined by the service. 
• And the operation then has child elements, representing parameters that are being passed in. 
• This operation, or procedure, has a single parameter, arg0, set to the value Google. 
• The names of the web services procedures, and the names and data types of each procedure’s parameters, are defined in the service’s WSDL document.

<soapenv:Body>

      <cod:getStockPrice>

         <arg0>Google</arg0>

      </cod:getStockPrice>

   </soapenv:Body>

• The response message also has a route envelope element. 
• Like the request, it declares a namespace indicating the SOAP version and the body has a namespace that’s unique to the web service. 
• These should always match the namespaces in the request. 
• If the call to the remote operation succeeds, the response message can be as simple as an envelope that contains a body. 
• And then resulting data within the body.

 <S:Body>

      <ns2:getStockPriceResponse xmlns:ns2="http://codenuclear.com/">

         <return>2100.0</return>

      </ns2:getStockPriceResponse>

   </S:Body>

• In this example, the response is an element named getStockPriceResponse. 
• That element contains a child element named return, which contains the resulting numeric value. As with the request, the data type of that value, whether it’s a string, integer, float or other. Is defined in the service’s WSDL document.

➤ The SOAP Fault

• The SOAP <Fault> is a subelement of the SOAP body, which is used for reporting errors.
• If the request fails for any reason, the server sends back a response containing a Fault element which is a child element of the body. 
• The body typically contains either valid response data or a fault, but not both.
• In SOAP, the Fault element has a number of child elements with fixed names, including Code, Reason, Role, and Detail. 
• These are the names of the elements in SOAP 1.2. In SOAP 1.1, they’re somewhat different. 
• The Code value can be one of a number of fixed values. 
• In SOAP 1.2, the value sender means that the client sent a malformed request message, that had an error, such an unrecognized operation name, or incorrect data types. 
• But it can also be receiver.

<S:Body>

      <S:Fault xmlns:ns4="http://www.w3.org/2003/05/soap-envelope">

         <faultcode>S:Server</faultcode>

         <faultstring>XML reader error: javax.xml.stream.XMLStreamException: ParseError at [row,col]:[6,25]

Message: The element type "arga0" must be terminated by the matching end-tag "</arga0>".</faultstring>

      </S:Fault>

   </S:Body>

---

10. Importance of The SOAP Attachments, Explaining the MIME Header

• Web services require the ability to send more than just text messages between services in a process. 
• Often it will involve complex data types such as language structures, multimedia/binary files, and other embedded messages. 
• This article takes a look at how the SOAP with Attachments specification can be used to send such information. 
• It provides a programming example of how to handle custom data type mapping and attachments in your SOAP services.
• As you know, SOAP is a simple, lightweight XML-based distributed computing protocol. The SOAP 1.1 specification essentially comprises three parts:

1. A framework for describing the contents of a SOAP message and how it's processed.
2. An encoding standard for objects sent over SOAP.
3. A mechanism for representing remote procedure calls using SOAP.

• A SOAP message is an XML document that comprises a SOAP envelope. Within the envelope is an optional SOAP header and a mandatory SOAP body. The SOAP message header represents the metadata of the message and provides a way to extend SOAP. The SOAP message body is the actual message payload. The details of a remote procedure call including the arguments are described in the envelope that is transported from one application to another over a selected protocol (e.g., HTTP). HTTP provides a firewall-friendly application-level protocol for communication between heterogeneous applications. The SOAP Messages with Attachments specification builds on SOAP 1.1.

• Before we discuss this specification, we should briefly consider the concept of a Multipurpose Internet Mail Extensions multipart. MIME is leveraged in the SOAP with Attachments specification as well as in other related Web services specifications such as WSDL (Web Services Description Language). Typically, e-mail messages with attachments are sent over the Internet using Simple Mail Transfer Protocol and MIME. SMTP is limited to 7-bit ASCII text with a maximum line length of a thousand characters which results in the inability to send attachments. MIME addresses these limitations by specifying message header fields and allowing different related objects such as attachments to be included in the message body in the form of a MIME multipart.

• For example, if the message body contains multiple independent objects of possibly different data types, the message body is divided into parts by boundaries. To indicate that the message body comprises a multipart structure of independent attachments, a Content-Type message header field is set.

• The Content-Type header can also be used to identify a Multipart structure with related MIME parts. RFC 2387 specifies the Multipart/Related Content-Type to provide a mechanism for representing an object that consists of related MIME body parts. As you'll see, the Multipart/Related Content-Type allows a SOAP message to reference attachments such as audio and image files.

• Armed with this basic knowledge of SOAP and MIME, let's discuss the concept of SOAP messages with attachments. Let's assume we use the MIME specifications to support SOAP messages with attachments and we package a SOAP 1.1 message as a part of a MIME multipart structure. Further, let's assume we provide a way for that SOAP 1.1 message to refer to attachments that are represented as other parts of that MIME multipart. In a nutshell, this is the approach described in the SOAP Messages with Attachments technical note.

• This note specifies how to package a SOAP 1.1 message with attachments using existing MIME specifications. A SOAP Message Package, which is a central concept in this specification, consists of a SOAP 1.1 message that can reference attachments, and any related attachments. A SOAP message package is built using the Multipart/Related Content-Type. The primary SOAP 1.1 message must be included in the root body part of the Multipart/Related container. Thus the type header of the Multipart container and the Content-Type header of the root body part will be the same (i.e., text/xml). The attachments in the Multipart container must be composed of a Content-ID MIME header or a Content-Location MIME header.

• For the SOAP message to reference attachments in the MIME container, the SOAP 1.1 encoding rules are used. In the specification a URI that is a value of an HREF attribute can be used to refer to a resource. Since each attachment in the MIME container has a URI reference in its Content-Location or Content-ID header, it's possible for the attachments to be referred to using the HREF attribute from the SOAP 1.1 message. To refer to an attachment with a specific Content-ID header value, the Content-ID Uniform Resource Locator scheme, "cid," is used, as defined in RFC 2111. So, for example, to refer to a MIME part (GIF image) with a Content-ID of 286.apache-soap.MYHOST, an HREF value of "cid:286.apache-soap. MYHOST" is used.

➤ MIME

• The MIME stands for Multi-Purpose Internet Mail Extensions. As the name indicates, it is an extension to the Internet email protocol that allows it’s users to exchange different kinds of data files over the Internet such as images, audio, and video. The MIME is required if text in character sets other than ASCII. Virtually all human-written Internet email and a fairly large proportion of automated email is transmitted via SMTP in MIME format. Actually, MIME was designed mainly for SMTP, but the content types defined by MIME standards are important also in communication protocols outside of email, such as HTTP. In 1991, Nathan Borenstein of Bellcore proposed to the IETF that SMTP be extended so that Internet (but mainly Web) clients and servers could recognize and handle other kinds of data than ASCII text. As a result, new file types were added to “mail” as a supported Internet Protocol file type.

• Now, let’s see the MIME headers. There are many sub parts come under MIME headers. Let’s see each in detail.

➤ MIME-Version

• MIME-Version header is used to indicate that the message is MIME formatted. This header is having a value of “1.0” typically. So this header will be as follows.

eg: MIME-Version: 1.0

• When the MIME was developed, the developers had a plan to further issue the newer versions, but the problems caused by changes in a standard discouraged further release of the same.

➤ Content-Type

• This header is used to describe the content type of the message. The Content-Type header includes the type and a sub-type parts

eg: Content-Type: text/plain

• Through the use of the multi-part type, MIME allows mail messages to have parts arranged in a tree structure where the leaf nodes are any non-multipart content type and the non-leaf nodes are a variety of multi-part types. This mechanism supports:

1. Simple text messages using text/plain (the default value for “Content-Type: “).
2. Text plus attachments (multipart/mixed with a text/plain part and other non-text parts). A MIME message including an attached file generally indicates the file’s original name with the “Content-disposition:” header, so the type of file is indicated both by the MIME content-type and the (usually OS-specific) filename extension.
3. Reply with original attached (multipart/mixed with a text/plain part and the original message as a message/rfc822 part).
4. Alternative content, such as a message sent in both plain text and another format such as HTML (multipart/alternative with the same content in text/plain and text/html forms).
5.  Image, audio, video, and application (for example, image/jpeg, audio/mp3, video/mp4, and application/msword and so on).
6. Many other message constructs.

• The original MIME specifications only described the structure of mail messages. 
• They did not address the issue of presentation styles. 
• The content-disposition header field was added in RFC 2183. It specifies the presentation style.
• There are two types of Content-Disposition:

1. Inline Content-Disposition
2. Attachment Content-Disposition

Inline Content-Disposition

• The Inline Content-Disposition would be automatically displayed when the message is shown.

Attachment Content-Disposition

• The Attachment Content-Disposition will not be displayed automatically. It needs the user action to get opened and displayed.

• The content-disposition header also provides fields for specifying the name of the file, the creation date, and modification date, which can be used by the reader’s mail user agent to store the attachment.
• Now a day, a good majority of mail user agents do not follow this prescription fully. The widely used Mozilla Thunderbird mail client makes its own decisions about which MIME parts should be automatically displayed, ignoring the content-disposition headers in the messages. Thunderbird prior to version 3 also sends out newly composed messages with inline content-disposition for all MIME parts.
• Many mail user agents also send messages with the file name in the name parameter of the content-type header instead of the filename parameter of the content-disposition header. This practice is discouraged – the file name should be specified either through just the filename parameter, or through both the filename and the name parameters.

➤ Content-Transfer-Encoding

• In June 1992, MIME (RFC 1341) defined a set of methods for representing binary data in formats other than ASCII text format. The content-transfer-encoding: MIME header has 2-sided significance:
• It indicates whether or not a binary-to-text encoding scheme has been used on top of the original encoding as specified within the Content-Type header:

1.  If such a binary-to-text encoding method has been used, it states which one.
2.  If not, it provides a descriptive label for the format of content, with respect to the presence of 8-bit or binary content.

• The RFC and the IANA’s list of transfer encodings define the values shown below, which are not case sensitive. Note that ‘7bit’, ‘8bit’, and ‘binary’ mean that no binary-to-text encoding on top of the original encoding was used. In these cases, the header is actually redundant for the email client to decode the message body, but it may still be useful as an indicator of what type of object is being sent. Values ‘quoted-printable’ and ‘base64’ tell the email client that a binary-to-text encoding scheme was used and that appropriate initial decoding is necessary before the message can be read with its original encoding (e.g. UTF-8).

---

11 . Different set of frameworks/libraries for SOAP

➤ Apache Axis

• Apache Axis (Apache eXtensible Interaction System) is an open-source, XML based Web service framework. It consists of a Java and a C++ implementation of the SOAP server, and various utilities and APIs for generating and deploying Web service applications. Using Apache Axis, developers can create interoperable, distributed computing applications. Axis development takes place under the auspices of the Apache Software Foundation.

➤ Apache CXF

• Apache CXF is an open-source, fully featured Web services framework. It originated as the combination of two open-source projects: Celtix developed by IONA Technologies and XFire developed by a team hosted at Codehaus. These two projects were combined by people working together at the Apache Software Foundation and the new name CXF was derived by combining "Celtix" and "XFire".

➤ CodeIgniter

• CodeIgniter is an open-source software rapid development web framework, for use in building dynamic web sites with PHP.
• CodeIgniter is loosely based on the popular model-view-controller(MVC) development pattern. 
• While controller classes are a necessary part of development under Codeigniter , models and views are optional. CideIgniter can be also modified to use Hierachical Model View Controller(HMVC) which allows developers to maintain modular grouping of Controller , models and view arranged in a sub-directory format.

➤ gSOAP

• gSOAP is a C and C++ software development toolkit for SOAP/XML web services and generic XML data bindings. The gSOAP tools generate efficient source code for XML serialization of any type of C/C++ data with zero-copy overhead.

➤ .NET Framework

• .NET Framework (pronounced as "dot net") is a software framework developed by Microsoft that runs primarily on Microsoft Windows. It includes a large class library named Framework Class Library (FCL) and provides language interoperability (each language can use code written in other languages) across several programming languages. Programs written for .NET Framework execute in a software environment (in contrast to a hardware environment) named Common Language Runtime (CLR), an application virtual machine that provides services such as security, memory management, and exception handling. As such, computer code written using .NET Framework is called "managed code". FCL and CLR together constitute the .NET Framework.

➤ Symfony

• Symfony is a PHP web application framework and a set of reusable PHP components/libraries. Symfony was published as free software on October 18, 2005 and released under the MIT license.

---

12. The Annotations in JAX-WS

---

---

	The @WebService annotation marks a Java class as implementing a Web service or  marks a service endpoint interface (SEI) as implementing a web service interface.
	The @WebMethod annotation denotes a method that is a web service operation. Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
	The @Oneway annotation denotes a method as a web service one-way operation that only has an input message and no output message. Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
	The @WebParam annotation customizes the mapping of an individual parameter to a web service message part and XML element. Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
	The @WebResult annotation customizes the mapping of a return value to a WSDL part or XML element. Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.
	The @HandlerChain annotation associates the web service with an externally defined handler chain. You can only configure the server side handler by using the @HandlerChain annotation on the Service Endpoint Interface (SEI) or the server endpoint implementation class. Use one of several ways to configure a client side handler. You can configure a client side handler by using the @HandlerChain annotation on the generated service class or SEI. Additionally, you can programmatically register your own implementation of the HandlerResolver interface on the Service, or programmatically set the handler chain on the Binding object.
	The @SOAPBinding annotation specifies the mapping of the web service onto the SOAP message protocol. Apply this annotation to a type or methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.The method level annotation is limited in what it can specify and is only used if the style property is DOCUMENT. If the method level annotation is not specified, the @SOAPBinding behavior from the type is used.

---

13. How a Web Service Can be Tested Using Different Approaches

• A testing strategy should actually integrate two approaches to ensure complete covering of Web services: Testing the messaging layer as well as the application layer. Indeed, testing software components ensure that the underlying application component is robust enough to meet the demands of the business service contract. These tests can then be placed into regression suites. The web services test strategy includes 6 main stages which we will discuss below.

➤ Validation of the WSDL

• Interfaces must be correctly described in a WSDL (Web Services Description Language) document. Messages must also conform to the contract specified in the WSDL describing the service, both in terms of the message content and the binding to the transport layer. The phase tests the foundation for a SOA implementation.

➤ Unit Testing

• Just like with testing of ordinary software components, unit testing is an important step to validate that these building blocks are working correctly. Also within web services, each operation must be exercised in isolation within the environment to confirm request and response. In particular, these tests will cover robustness of the operations by using so-called negative test cases (that check edge conditions and empty values etc).

➤ Functional Testing

• The goal of this testing is fairly straightforward: to ensure that the server delivers appropriate responses for the given requests. However, due to the complexity of Web services, this task is far from simple. With most Web services, it is impossible to anticipate exactly what types of requests clients will send. Enumerating all possible requests is not feasible because the space of possible inputs is either unbounded or intractably large. As a result, it is important to verify with realistic business use cases whether the server can handle a wide range of request types and parameters.

➤ Regression Testing

• After you have verified the server's functionality, rerun the functional test suite on a regular basis to ensure that modifications do not cause unexpected changes or failures. A common technique is to send various requests, manually confirm the responses, and then save them as a regression control. These regression tests can be incorporated into a regular automated build process. When regression tests are run frequently, regressions are easy to fix because they can be directly attributed to the few changes made since the last time the test was run.

➤ Load Testing

• The goal of load testing is to verify the performance and functionality of the service under heavy load. It isavital steps to make sure the services will delivered the required Quality of Service (QoS) for the customers / users of the system.

• The best way to start load testing is to have multiple test clients run the complete functional test, including request submissions and response verifications. When load testing ignores the functionality verification process and focuses solely on load-rate metrics, it risks overlooking critical flaws (such as functionality problems that surface only under certain loads).