API Basics

This document will cover the basics of web services,

their characteristics, components, etc.
TABLE OF CONTENTS
WHAT ARE WEB SERVICES?............................................................................................................................. 2
Benefits of using Web Services...................................................................................................... 3
Characteristics:............................................................................................................................... 3
Components of Web Services.......................................................................................................................... 4
XML-RPC........................................................................................................................................ 4
SOAP (Simple Object Access Protocol):......................................................................................... 4
UDDI (Universal Description, Discovery and Integration)................................................................4
WSDL (Web Services Description Language)................................................................................5
How Does a Web Service Work?....................................................................................................................... 6
XML Document Structure (Extensible Mark-up Language).............................................................6
XML Declaration............................................................................................................................. 6
Document Type Declaration............................................................................................................ 7
Why use a DTD?............................................................................................................................. 8
Document Body.............................................................................................................................. 8
SOAP (Simple Object Access Protocol)................................................................................................. 9
SOAP - Message Structure............................................................................................................. 9
SOAP - Envelope Element............................................................................................................ 10
SOAP - Header Element............................................................................................................... 10
Actor attribute................................................................................................................................ 11
Must-Understand attribute............................................................................................................. 11
SOAP - Body Element................................................................................................................... 11
SOAP - Fault Element................................................................................................................... 12
WSDL (Web Services Description Language)....................................................................................................... 15
Features of WSDL........................................................................................................................ 15
WSDL – Elements......................................................................................................................... 15
Reference:............................................................................................................................................ 17
 WHAT ARE WEB SERVICES?
A web service is any piece of software that makes itself available over the internet and uses a
standardized XML messaging system.

In a Web service, Web technology such as HTTP, originally designed for human-to-machine
communication, is utilized for machine-to-machine communication, more specifically for transferring
machine readable file formats such as XML and JSON.

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 and so on.

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.

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.

To summarize, a complete web service is, therefore, any service that:

 Is available over the Internet or private (intranet) networks
 Uses a standardized XML messaging system
 Is not tied to any one operating system or programming language
 Is self-describing via a common XML grammar
 Is discoverable via a simple find mechanism

Benefits of using Web Services

 Exposing the Existing Function on the network
 Interoperability
 Standardized Protocol
 Low Cost of Communication

Characteristics:
 XML Based
 Loosely coupled
 Coarse-Grained
 Ability to be Synchronous or Asynchronous
 Supports Remote Procedure Calls(RPCs)
 Supports Document Exchange
 Components of Web Services
The basic web services platform is XML + HTTP. All the standard web services work using the
following components:

 XML-RPC
 SOAP (Simple Object Access Protocol)
 UDDI (Universal Description, Discovery and Integration)
 WSDL (Web Services Description Language)

XML-RPC

This is the simplest XML-based protocol for exchanging information between computers.

 XML-RPC is a simple protocol that uses XML messages to perform RPCs.

 Requests are encoded in XML and sent via HTTP POST.
 XML responses are embedded in the body of the HTTP response.
 XML-RPC is platform-independent.
 XML-RPC allows diverse applications to communicate.
 A Java client can speak XML-RPC to a Perl server.
 XML-RPC is the easiest way to get started with web services.

SOAP (Simple Object Access Protocol):

SOAP is an open-standard, XML-based messaging protocol for exchanging information among

computers. SOAP can be used in a variety of messaging systems and can be delivered via a variety of
transport protocols, the initial focus of SOAP is remote procedure calls transported via HTTP.

 SOAP is a communication protocol designed to communicate via Internet.

 SOAP can extend HTTP for XML messaging.
 SOAP provides data transport for Web services.
 SOAP can exchange complete documents or call a remote procedure.
 SOAP can be used for broadcasting a message.
 SOAP is platform- and language-independent.
 SOAP is the XML way of defining what information is sent and how.
 SOAP enables client applications to easily connect to remote services and invoke remote
methods.
 Other frameworks including CORBA, DCOM, and Java RMI provide similar functionality to
SOAP, but SOAP messages are written entirely in XML and are therefore uniquely platform-
and language-independent.

UDDI (Universal Description, Discovery and Integration)

 UDDI is an XML-based standard for describing, publishing, and finding web services.
 UDDI stands for Universal Description, Discovery, and Integration.
  UDDI is a specification for a distributed registry of web services.
 UDDI is platform independent, open framework.
 UDDI can communicate via SOAP, CORBA, and Java RMI Protocol.
 UDDI uses WSDL to describe interfaces to web services.
 UDDI is seen with SOAP and WSDL as one of the three foundation standards of web services.
 UDDI is an open industry initiative enabling businesses to discover each other and define
how they interact over the Internet.

WSDL (Web Services Description Language)

WSDL is an XML-based language for describing web services and how to access them.

 WSDL stands for Web Services Description Language.

 WSDL was developed jointly by Microsoft and IBM.
 WSDL is an XML based protocol for information exchange in decentralized and distributed
environments.
 WSDL is the standard format for describing a web service.
 WSDL definition describes how to access a web service and what operations it will perform.
 WSDL is a language for describing how to interface with XML-based services.
 WSDL is an integral part of UDDI, an XML-based worldwide business registry.
 WSDL is the language that UDDI uses.
 WSDL is pronounced as 'wiz-dull' and spelled out as 'W-S-D-L'.
 How Does a Web Service Work?

A web service enables communication among various applications by using open standards such as
HTML, XML, WSDL, and SOAP. A web service takes the help of:
 XML to tag the data
 SOAP to transfer a message
 WSDL to describe the availability of service.

XML Document Structure (Extensible Mark-up Language)

An XML document consists of declarations, elements, comments, character references, and
processing instructions, collectively known as the markup.

An XML document consists of three parts, in the order given:

1. An XML declaration (which is technically optional, but recommended in most normal cases)
2. A document type declaration that refers to a DTD (which is optional, but required if you want
validation)
3. A body or document instance (which is required)

XML Declaration

The XML declaration is a processing instruction that identifies the document as being XML.
This declaration also indicates whether the document can be validated by referring to an external
Document Type Definition (DTD).
NOTE: DTDs are the set of rules that describes the structure of an XML document.

The basic XML declaration is:

<?xml version="1.0" ?>

An XML declaration consists of the literal sequence '<?xml', followed by the required version
information, followed by optional encoding and standalone declarations, followed by an optional
amount of white space, and terminating with the literal sequence '?>'. In this notation, a question
mark not contained in quotes means that the term that precedes it is optional.

<?xml
version="version_number"
encoding="encoding_declaration"
standalone="standalone_status" ?>

There are few things to keep in mind while declaring the XML
1. If the XML declaration is included, it must be suited at the first position of the first line in the
XML document.
2. If the XML definition is included, it must contain the version number attribute
 3. If all of the attributes are declared in XML declaration, they must be placed in the order
shown above.
4. If any elements, attributes, or entities are used in XML document that are referred or
defined in an external DTD, standalone=”no” must be included.
5. The XML declaration must be in lower case (except for the encoding declarations).
6. The optional encoding part of the declaration tells the XML processor (parser) how to
interpret the bytes based on a particular character set. The default encoding is UTF-8, which
is one of seven character-encoding schemes used by the Unicode standard, also used as the
default for Java.

<?xml version="1.0" encoding="UTF-8" ?>

Attribute
Possible Attribute Value: Attribute Description:
Name:

Specifies the version of the XML standard that the

version 1.0 XML document conforms to. The version attribute
must be included if the XML declaration is declared.

UTF-8, UTF-16, ISO-10646-

UCS-2, ISO-10646-UCS-4, ISO- These are the encoding names of the most common
encoding
8859-1 to ISO-8859-9, ISO- character sets in use today.
2022-JP, Shift_JIS, EUC-JP

Use 'yes' if the XML document has an internal DTD.

standalone yes, no Use 'no' if the XML document is linked to an external
DTD, or any external entity references.

Document Type Declaration

 The document type declaration follows the XML declaration. The purpose of this declaration
is to define the legal building blocks of an XML document.
 The DTD consists of an internal, or references an external Document Type Definition (DTD).
 It can also have both internal and external DTDs.

The general syntax is:

<!DOCTYPE RootElement (SYSTEM | PUBLIC)

ExternalDeclarations? [InternalDeclarations]? >

Where <!DOCTYPE is a literal string, RootElement is whatever you name the outermost element of

your hierarchy, followed by either the literal keyword SYSTEM or PUBLIC. The optional
ExternalDeclarations portion is typically the relative path or URL to the DTD that describes your
document type. If there are InternalDeclarations, they must be enclosed in square brackets.
 Below are the few points to remember while declaring DTD

1. The Document Type Declaration must be placed between the XML declaration and the first
element (root element) in the document.
2. The keyword DOCTYPE must be followed by the name of the root element in the XML
document.
3. The keyword DOCTYPE must be in upper case.
4. If any elements, attributes, or entities are used in the XML document that are referenced or
defined in an external DTD, standlone=”no” must be included in the XML declaration.

Why use a DTD?

XML provides an application independent way of sharing data. With a DTD, independent groups of
people can agree to use a common DTD for interchanging data. Your application can use a standard
DTD to verify that data that you receive from the outside world is valid. You can also use a DTD to
verify your own data.

Document Body

The document body, or instance, is the bulk of the information content of the document. Whereas
across multiple instances of a document of a given type (as identified by the DOCTYPE) the XML
prolog will remain constant, the document body changes with each document instance (in general).
This is because the prolog defines (either directly or indirectly) the overall structure while the body
contains the real instance-specific data.

Because the document type declaration specifies the root element, this must be the first element the
parser encounters. If any other element but the one identified by the DOCTYPE line appears first, the
document is immediately invalid.

Below shows a very simple XHTML 1.0 document. The DOCTYPE is "html" (not "xhtml"), so the
document body begins with <html ....> and ends with </html>.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>XHTML 1.0</title>
</head>
<body>
<h1>Simple XHTML 1.0 Example</h1>
<p>See the <a href="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">DTD</a>.</p>
</body>
</html>
 SOAP (Simple Object Access Protocol)
These points briefly describes the nature of SOAP −
 SOAP is a communication protocol designed to communicate via Internet.
 SOAP can extend HTTP for XML messaging.
 SOAP provides data transport for Web services.
 SOAP can exchange complete documents or call a remote procedure.
 SOAP can be used for broadcasting a message.
 SOAP is platform- and language-independent.
 SOAP is the XML way of defining what information is sent and how.
 SOAP enables client applications to easily connect to remote services and invoke remote
methods.

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

 Envelope − Defines the start and the end of the message. It is a mandatory element.
 Header − Contains any optional attributes of the message used in processing the message,
either at an intermediary point or at the ultimate end-point. It is an optional element.
 Body − Contains the XML data comprising the message being sent. It is a mandatory
element.
 Fault − An optional Fault element that provides information about errors that occur while
processing the message.

SOAP - Message Structure

The following block is the general structure of a SOAP message −

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

<SOAP-ENV:Header>
...
...
</SOAP-ENV:Header>

<SOAP-ENV:Body>
...
...
<SOAP-ENV:Fault>
...
...
</SOAP-ENV:Fault>
...
</SOAP-ENV:Body>
 </SOAP_ENV:Envelope>

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

 Envelope − Defines the start and the end of the message. It is a mandatory element.
 Header − Contains any optional attributes of the message used in processing the message,
either at an intermediary point or at the ultimate end-point. It is an optional element.
 Body − Contains the XML data comprising the message being sent. It is a mandatory
element.
 Fault − An optional Fault element that provides information about errors that occur while
processing the message.

SOAP - Envelope Element

The SOAP envelope indicates the start and the end of the message so that the receiver knows when
an entire message has been received. The SOAP envelope solves the problem of knowing when you
are done receiving a message and are ready to process it. The SOAP envelope is therefore basically
a packaging mechanism.

Below mentioned are some important points about SOAP envelope element −
 Every SOAP message has a root Envelope element.
 Envelope is a mandatory part of SOAP message.
 Every Envelope element must contain exactly one Body element.
 If an Envelope contains a Header element, it must contain no more than one, and it must
appear as the first child of the Envelope, before the Body.
 The envelope changes when SOAP versions change.
 The SOAP envelope is specified using the ENV namespace prefix and the Envelope element.
 The optional SOAP encoding is also specified using a namespace name and the
optional encodingStyle element, which could also point to an encoding style other than the
SOAP one.
 A v1.1-compliant SOAP processor generates a fault upon receiving a message containing the
v1.2 envelope namespace.
 A v1.2-compliant SOAP processor generates a VersionMismatch fault if it receives a message
that does not include the v1.2 envelope namespace.

SOAP - Header Element

The optional Header element offers a flexible framework for specifying additional application-level
requirements. For example, the Header element can be used to specify a digital signature for
password-protected services. Likewise, it can be used to specify an account number for pay-per-use
SOAP services.
Below mentioned are few important points about SOAP header element to take note of −
 It is an optional part of a SOAP message.
 Header elements can occur multiple times.
 Headers are intended to add new features and functionality.
 The SOAP header contains header entries defined in a namespace.
  The header is encoded as the first immediate child element of the SOAP envelope.
 When multiple headers are defined, all immediate child elements of the SOAP header are
interpreted as SOAP header blocks.
A SOAP Header can have the following two attributes –

Actor attribute
The SOAP protocol defines a message path as a list of SOAP service nodes. Each of these
intermediate nodes can perform some processing and then forward the message to the next
node in the chain. By setting the Actor attribute, the client can specify the recipient of the
SOAP header.

Must-Understand attribute
It indicates whether a Header element is optional or mandatory. If set to true, the recipient
must understand and process the Header attribute according to its defined semantics, or
return a fault.

The following example shows how to use a Header in a SOAP message.

<?xml version="1.0"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV=" http://www.w3.org/2001/12/soap-envelope" SOAP-

ENV:encodingStyle=" http://www.w3.org/2001/12/soap-encoding">

<SOAP-ENV:Header>
<t:Transaction xmlns:t="http://www.tutorialspoint.com/transaction/" SOAP-
ENV:mustUnderstand="true">5</t:Transaction>
</SOAP-ENV:Header>
...
...
</SOAP-ENV:Envelope>

SOAP - Body Element

The SOAP body is a mandatory element that contains the application-defined XML data being
exchanged in the SOAP message. The body must be contained within the envelope and must follow
any headers that might be defined for the message.
The body is defined as a child element of the envelope, and the semantics for the body are defined
in the associated SOAP schema.
The body contains mandatory information intended for the ultimate receiver of the message. For
example –

<?xml version="1.0"?>

<SOAP-ENV:Envelope>
........
 <SOAP-ENV:Body>
<m:GetQuotation xmlns:m="http://www.tp.com/Quotation">
<m:Item>Computers</m:Item>
</m:GetQuotation>
</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The example above requests a quotation of computer sets. Note that the m:GetQuotation and the
Item elements above are application-specific elements. They are not a part of the SOAP standard.
Here is the response to the above query –

<?xml version="1.0"?>

<SOAP-ENV:Envelope>
........
<SOAP-ENV:Body>
<m:GetQuotationResponse xmlns:m="http://www.tp.com/Quotation">
<m:Quotation>This is Qutation</m:Quotation>
</m:GetQuotationResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Normally, the application also defines a schema to contain semantics associated with the request
and response elements.
The Quotation service might be implemented using an EJB running in an application server; if so,
the SOAP processor would be responsible for mapping the body information as parameters into and
out of the EJB implementation of the GetQuotationResponse service. The SOAP processor could also
be mapping the body information to a .NET object, a CORBA object, a COBOL program, and so on.

SOAP - Fault Element

If an error occurs during processing, the response to a SOAP message is a SOAP fault element in the
body of the message, and the fault is returned to the sender of the SOAP message.
The SOAP fault mechanism returns specific information about the error, including a predefined
code, a description, and the address of the SOAP processor that generated the fault.

Below mentioned are few important points about SOAP fault element to take note of −
 A SOAP message can carry only one fault block.
 Fault is an optional part of a SOAP message.
 For HTTP binding, a successful response is linked to the 200 to 299 range of status codes.
 SOAP Fault is linked to the 500 to 599 range of status codes.

The SOAP Fault has the following sub elements −

 Sub-element Description

<faultCode> It is a text code used to indicate a class of errors. See the next Table for a listing of
predefined fault codes.

<faultString> It is a text message explaining the error.

<faultActor> It is a text string indicating who caused the fault. It is useful if the SOAP message
travels through several nodes in the SOAP message path, and the client needs to
know which node caused the error. A node that does not act as the ultimate
destination must include a faultActor element.

<detail> It is an element used to carry application-specific error messages. The detail

element can contain child elements called detail entries.

The faultCode values defined below must be used in the faultcode element while describing faults.

Error Description

SOAP-ENV:VersionMismatch Found an invalid namespace for the SOAP Envelope element.

SOAP-ENV:MustUnderstand An immediate child element of the Header element, with the

mustUnderstand attribute set to "1", was not understood.

SOAP-ENV:Client The message was incorrectly formed or contained incorrect

information.

SOAP-ENV:Server There was a problem with the server, so the message could not
proceed.

The following code is a sample Fault. The client has requested a method named  ValidateCreditCard,
but the service does not support such a method. This represents a client request error, and the
server returns the following SOAP response –

<?xml version='1.0' encoding='UTF-8'?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>
<faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode>

<faultstring xsi:type="xsd:string">
Failed to locate method (ValidateCreditCard) in class (examplesCreditCard) at
/usr/local/ActivePerl-5.6/lib/site_perl/5.6.0/SOAP/Lite.pm line 1555.
 </faultstring>

</SOAP-ENV:Fault>
</SOAP-ENV:Body>

</SOAP-ENV:Envelope>
 WSDL (Web Services Description Language)
WSDL is the standard format for describing a web service. It 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.

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

WSDL – Elements
The three major elements of WSDL that can be defined separately are:
 Types
 Operations
 Binding

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.
 Documentation: This element is used to provide human-readable documentation and can
be included inside any other WSDL element.
 Import: This element is used to import other WSDL documents or XML Schemas.
Reference:

 https://www.owasp.org/index.php/Web_Service_Security_Testing_Cheat_Sheet
 http://www.soapui.org/
 http://www.techrepublic.com/blog/software-engineer/how-to-test-web-services-
with-soapui/
 http://www.techrepublic.com/blog/programming-and-development/easily-test-
web-services-with-soapui/699
 http://cdn.softwaretestinghelp.com/wp-
content/qa/uploads/2006/12/Automated-Testing.png