Chat with us, powered by LiveChat Creating an Example Web Service. Page 42 Chapter 3. Chapter 3 Chapter 3 – Alternative Formats - Study Help

Creating an Example Web Service. Page 42 Chapter 3.
Chapter 3
Chapter 3 – Alternative Formats

For submission : Read carefully “Using the Microsoft Stack” and “Using the Linux Apache MySQL PHP (LAMP) Stack” or 2 different approaches for creating a web service. Then
(a) compare the two approaches and
(b) explain 2 advantages of each approach relative to the other.

Creating Consumable Web
Services for Mobile Devices


! Understanding web services

! Using web service languages (formats)

! Creating an example service

! Debugging web services

Many of today’s mobile applications are personalized, and are not useful if they can only
access the data on the phone. For a user to get, for example, sports scores, retrieve stock
quotes, or perform accounting work, the mobile device needs to communicate with one or
more servers. The best way to achieve this communication is through web services.

This chapter covers what a web service is, the technologies involved in web services, and how
to create web services on the Windows platform and the Linux platform. Four different
walkthroughs show you how to create web services with four different technologies.

A web service enables two electronic devices to communicate over the Internet. The World
Wide Web Consortium (W3C) defi nes web service as “a software system designed to support
interoperable machine-to-machine interaction over a network.” In practice this means a server
communicating over port 80 or port 443 in plain text to the client.

Other methods of communication are remote procedure calls (RPC), the distributed component
object model (DCOM), and the common object request broker architecture (CORBA). These
methods of communication don’t work well through the Internet due to fi rewalls and the data


c03.indd 37c03.indd 37 28/07/12 5:49 PM28/07/12 5:49 PM


formats they use. Typically their data formats are specifi c to whatever tool created the service,
and it becomes a signifi cant challenge to have a Java application read data from a .NET or C++
application. They generally also use a specifi c port, which requires IT departments or, even worse,
home users, to troubleshoot and confi gure their fi rewalls to allow the application to communicate.
Finally those technologies don’t work well through the Internet because they aren’t designed to work
with the Hypertext Transfer Protocol.


A port is similar to a TV channel. News comes in on the news channel, sports on
ESPN, and so on. Instead of watching the channels, computer applications are
listening on port numbers. The information coming to the computer on that port
number is routed to the application listening on that port number. For example,
when your computer requests a web page from a web server, it issues the request
through port 80. That traffi c is delivered by the server’s operating system to
a HyperText Transfer Protocol (HTTP) server application such as Microsoft’s
Internet Information Services (IIS) or the Apache Web Server. Connecting with a
fi le transfer protocol (FTP) client to the same server, the FTP software uses port 21.
Both FTP and HTTP traffi c are going to the same computer with the same address,
so having different ports enables the server to route the traffi c to the
correct application.

Examples of Web Services
Because you are reading this book, I’m assuming you are a developer or have some type of
development background, so I’ll use the StackOverfl ow web service as an example. You can view
my StackOverfl ow profi le by using a nice user interface StackOverfl ow has created to access their
web service by going to
find-david-silva-smith in a web browser. That URL is a query which shows the data from my
StackOverfl ow profi le. To view my profi le data in its raw form to compare it to the pretty formatted
data just shown, enter this URL in a browser:

Think how easily an application can be written using that data. This is the power of web services.
By making your data easily consumable through web services, others can use the data you have
created in ways you never imagined.

Not convinced yet? What if you wanted to display the weather for Lansing, Michigan, on your web
page? How hard would that be to program? For starters, you would have to purchase equipment
to measure the temperature, wind speed, and humidity, which could be expensive. Then you would
have to program that equipment to report the information to a web server, which would then
display that information on your web page. Wow, this is sounding diffi cult, and there are many
issues that haven’t been addressed yet, such as reliability. Instead of doing all that work, leveraging a

c03.indd 38c03.indd 38 28/07/12 5:49 PM28/07/12 5:49 PM

What Is a Web Service? ” 39

web service will be much faster. Simply type this URL into a web browser:
.com/ig/api?weather=Lansing,MI. No equipment required, no risk of schedule overruns, and
if requirements change and the software needs to display the weather for Lake Odessa instead of
Lansing, you just replace the Lansing,MI on the end of the URL with Lake%20Odessa,MI.


Not all characters are valid in uniform resource locators (URLs). A space is one
such character — it is represented as %20. The percent sign indicates that the follow-
ing two hexadecimal characters represent a single character — 20 in hexadecimal
is 32 in decimal, which is the ASCII code for space. If that isn’t confusing enough,
different characters are valid in different parts of a URL. To encode a URL, use the
JavaScript encodeURI() method or the equivalent function in your programming
language. For parts of a URL, use the JavaScript encodeURIComponent() method
or the equivalent function in your programming language. This JavaScript code
shows an example of when this difference is important:

var url = ‘
large images.aspx?folder=2012/April’;
var urlCorrect = ‘
large images.aspx?folder=’
var queryCorrect = ‘2012/April’;
document.write(encodeURI(urlCorrect) +

It outputs:

The fi rst two URLs are invalid because the URL wasn’t encoded correctly. The
third URL is correctly encoded.

Advantages of Web Services
The primary advantages web services provide are ease of access and ease of consumption. Web
services advantages stem from simplicity. Usage of web services for data exchange has exploded due
to these advantages.

c03.indd 39c03.indd 39 28/07/12 5:49 PM28/07/12 5:49 PM


Web services are easy to access because they use the same World Wide Web technologies such as web
browsers and web servers that power the Internet. These technologies have proven to be robust and
work great for web services just as they work great for delivering web pages. They have no
fi rewall issues with special ports like other communication technologies, and all modern
programming languages provide a way to get web pages and, therefore, to consume web services.

The second advantage of web services over other technologies is the consumability, which is the
ability to understand what the server is communicating. Web services use plain text for this. Other
technologies like RPC, DCOM, and CORBA typically use the in-memory representation of their
objects for transmission or use a custom data exchange format. These complexities make it expensive
for languages to interoperate with the information. The memory representations don’t have friendly
text like 48906, which most people can guess contains ZIP code information;
the server might send something like 1011111100001010, which could represent many pieces of
information. This discussion leads us into the next section, which discusses web service languages.

For communication to occur between two people they need to speak the same language. Computer
systems work the same way — they also need to use the same language. Most computer languages that
are widely known, such as C++, enable humans to talk to computers. But those computer languages are
hard for both computers and humans to understand because computers only understand zeros and ones,
and represent all data as zeros and ones. For example, the number 5 is represented as 00000101 in a
computer. A lowercase h is represented as 01101000, and 01001000 represents an uppercase H. Binary
representations are the most effi cient way for two computer systems to exchange data.

One of the reasons web services have been so successful is because of their self-describing nature.
Instead of giving a number like 5 and hoping the user of the web service knows that 5 is a weight,
an age, or dollars, the 5 is described in a service like this: 5
. This states clearly the measurement is for length and is 5 inches.

Format choice is an important decision — it impacts the ease of accessing the web service and the
performance of your application. When designing a web service, consider how the service will be
accessed. For example, mobile devices have less processing power than their desktop counterparts,
and the different platforms (BlackBerry, Windows Phone, Android, and iOS) have different
programming APIs available for accessing and consuming the data. The two self-describing formats
that have taken off for web services are XML and JSON. I recommend sticking with one of these
two formats to maximize the ease of consuming the services and maximize developer productivity.

eXtensible Markup Language (XML)
XML was designed as a way to describe documents, but it took off as a data interchange format
after it was introduced. XML was envisioned to be a simple human-readable language; for example,
a person object can be represented like this in XML:


c03.indd 40c03.indd 40 28/07/12 5:49 PM28/07/12 5:49 PM

Web Services Languages (Formats) ” 41

And the same person can also be represented like this:

Both XML fragments are easy for a person to understand, but different representations make it
harder for programmers to write correct software. Having a single agreed-upon representation of
the data will speed up your development effort.

XML enables you to defi ne the language systems used to communicate by creating an XML Schema
Document (XSD). This enables software to verify an XML document conforms to a predefi ned
contract. For example, the XSD can specify that the cost of a movie must be a number. XSD
also provides the benefi t of enabling tools to generate code based on the XSD. Programmers can
increase productivity by feeding their programming tool an XSD fi le and getting back code they
can immediately use to interact with the data. Without the XSD fi le programmers have to write code
to understand the XML.

One of the reasons for choosing XML is the maturity of the platform. It has been around since
February 1998. It has many tools around it — XPath, XQuery, XSLT, and XSD. Since it is a mature
language, many systems work well with XML. These advantages make XML a good choice for data
interchange and it may even be required for some projects to work with existing systems.

eXtensible Stylesheet Language Transformations (XSLT)
XSLT is used to transform a document into another representation. Initially it was envisioned as
primarily changing XML data documents into representations for human consumption, such as
XHTML. Another common use is applying an XSLT transformation to one application’s XML
output to be used by another application that doesn’t understand the original representation.

The following example shows how XSLT can transform an XML data fragment for display on a
web page.

This fragment: 30 would better be displayed on a web page like
this: Age:30.

The following XSLT will loop through each element in the XML with the name of person. Within
each person node, the XSLT will then output the span tag with the value of the age element included
within the span tag.


XQuery is used to retrieve a subset of data from a full XML document, like a SQL query is used to
retrieve a subset of data from a database.

This example shows how to get the total amount paid for this sample order:

c03.indd 41c03.indd 41 28/07/12 5:49 PM28/07/12 5:49 PM


The following XQuery returns the sum:


For testing or learning XQuery, a handy online sandbox is:

JavaScript Object Notation (JSON)
JSON was created in 2001 and came into use by Yahoo in 2005. JSON has few rules, few base types,
and is human readable. JSON schema enables document validation, but this is rarely used. JSON is a
great format for transmitting data between systems because it is simple, text based, and self-describing.

A person can be represented in JSON like this:

firstName : “David”,
lastName : “Smith”

One thing to watch out for is how dates are represented in JSON. There is no base type of date
and there is no standard way to represent dates. It is recommended to represent dates using the
International Standards Organization 8601 format. In ISO-8601 dates look like this: 1997-07-
16T19:20:30.45+01:00. Representing dates in ISO-8601 keeps them human readable, ensures
programming languages can parse them, and keeps time zone information.

Choosing ISO-8601 as the default data interchange format for projects is a good idea. Using JSON
will reduce the amount of time spent dealing with serialization issues.

Transferring Nontextual Data
Both JSON and XML create human-readable text documents. What happens if a service needs to
transmit or receive an image, a video, or a PDF document, such as a check image for a fi nancial
service or a video clip for a public safety service? This type of nontextual data is called binary data.
When transmitting binary data as text, it needs to be Base64 encoded so it can be represented with
the rest of the data. Base64 encoding comes with two downsides. First, the size of the text representa-
tion increases by 33 percent. Second, there is additional processing overhead by both the sender and
receiver for encoding or decoding the Base64 data to binary and vice versa.

Having talked about the technologies behind creating a consumable web service, this section shows
how to create a consumable web service in a Linux Apache PHP environment, and three different
service delivery technologies on the Microsoft .NET stack: WCF, OData, and ASP.NET MVC.

c03.indd 42c03.indd 42 28/07/12 5:49 PM28/07/12 5:49 PM

Creating an Example Web Service ” 43

Using the Microsoft Stack
The .NET platform has a variety of technologies enabling the easy creation of consumable web
services. This section walks through creating a database and sample data for the services to
operate on. The rest of the section shows how to create the service in three .NET technologies:
WCF, OData, and MVC.

Creating the Datastore
The WCF, OData, and MVC walkthroughs later in this section all assume the database script from
this section has been executed.

The example services will expose a simple data model consisting of two tables: Leagues and
DerbyNames. Some of the Gravity Works staff are Roller Derby fans. They noticed the players had
interesting names and decided their information (which is publicly available) would make a good
example service.

Figure 3-1 shows a database diagram of the
tables the script will create.

Open SQL Server Management Studio 2008
and connect to the local SQL Server instance
running on the machine. Open a new query
window and run the SQL-Server-Create-
Derby-Database script (full SQL script can
be found within the download section for this book at to create the tables
and insert the data used for the rest of the walkthroughs:

After running the script, SQL Server Management Studio will display “Query Executed
Successfully.” The walkthroughs in this section use this database to retrieve data.

Using Windows Communication Foundation
Windows Communication Foundation (WCF) is a .NET Framework library designed for developers to
create communication endpoints for software. Web services are software communication
endpoints, so on the surface WCF seems like an ideal choice for creating consumable web services.
Unfortunately, WCF is designed for a broad number of communication scenarios, and this broad
set of capabilities introduces a lot of complexity that is not necessary for web services. For example,
WCF supports reliable sessions, transactions, TCP, named pipes, Microsoft Message Queuing,
activity tracing, and Windows Management Instrumentation.

This walkthrough assumes the following software is installed:

! ASP.NET 4.0

! Visual Studio 2010

! IIS 7.5

! Microsoft SQL Server 2008 R2

FIGURE 3#1: Database diagram

c03.indd 43c03.indd 43 28/07/12 5:49 PM28/07/12 5:49 PM


1. Open Visual Studio and select File # New Project to create a new project.
2. In the New Project template selection screen, open the Visual C# node and select the WCF


3. From the WCF project types that display, select WCF Service Application. If that project type
does not display, ensure the fi lter at the top of the dialog box is set to .NET Framework 4.

4. Set the project name to DerbyNamesService and click OK, as shown in Figure 3-2.

FIGURE 3#2: New WCF Service Application

For ease of database access this walkthrough uses LINQ to SQL. LINQ to SQL is an Object
Relational Mapper technology that ships with the .NET Framework. Using LINQ requires an addi-
tional project reference to System.Data.Linq.

To add the reference, right-click the References node of the DerbyNamesService project and select
Add Reference.

In the Add Reference dialog box, fi nd System.Data.Linq and click the Add button as shown in
Figure 3-3.

c03.indd 44c03.indd 44 28/07/12 5:49 PM28/07/12 5:49 PM

Creating an Example Web Service ” 45

After adding the System.Data.Linq reference, you need to create a class to access the data. To do
this, right-click the DerbyNamesService project and choose Add # New Item as shown in Figure 3-4.

FIGURE 3#3: Add Reference dialog box

FIGURE 3#4: Add New Item

c03.indd 45c03.indd 45 28/07/12 5:49 PM28/07/12 5:49 PM


In the Add New Item dialog box, select Class, name it DerbyContext, and click the Add button as
shown in Figure 3-5.

FIGURE 3#5: Add New Class

The DerbyContext class will provide the data. To represent the data as .NET objects, add two more
code fi les: DerbyNames and Leagues. The DerbyNames class will contain the information on a derby
player. Make the DerbyNames.cs fi le contain this code:

using System;
using System.Data.Linq.Mapping;

namespace DerbyNamesService
public class DerbyNames
[Column(IsPrimaryKey = true)]
public int DerbyNameId;
public string Name;

c03.indd 46c03.indd 46 28/07/12 5:49 PM28/07/12 5:49 PM

Creating an Example Web Service ” 47

public string Number;
public DateTime? DateAdded;
public string League;

The Leagues class will contain information about the derby leagues, such as the league name. Make
the Leagues.cs fi le contain this code:

using System.Data.Linq.Mapping;

namespace DerbyNamesService
public class Leagues
public int LeagueId;
public string LeagueName;
public string URL;
public string StateProvince;
public string CountryCode;

The DerbyContext will be the class providing access to the database from the DerbyService class.
Modify the DerbyContext.cs code to contain this code:

using System.Data.Linq;
using DerbyNamesService;

namespace DerbyNamesService
public class DerbyContext : DataContext
public Table DerbyNames;
public Table Leagues;
public DerbyContext()
: base(“Data Source=.;Initial Catalog=DerbyNames;
User Id=webUser;Password=webuser;”)


c03.indd 47c03.indd 47 28/07/12 5:49 PM28/07/12 5:49 PM


In the Visual Studio Solution Explorer, rename Service1.svc to DerbyService.svc and then
rename IService1.cs to IDerbyService.cs. If Visual Studio prompts if you would like to rename
all project references, click Yes. This step is just a cleanup step to rename the default fi les Visual
Studio creates for you. The IDerbyService interface defi nes the contract for the service — in other
words, this interface will expose the operations the service provides. Change the IDerbyService.cs
fi le to contain the following code:

using System.Collections.Generic;
using System.ServiceModel;

namespace DerbyNamesService
public interface IDerbyService
public IEnumerable PlayerNames();

public IEnumerable Leagues();

With the service contract defi ned, a class to implement the operations defi ned by the IDerbyService
contract needs to be created. The DerbyService.svc.cs fi le will implement the contract. In other
words, the contract states what the service will do and the DerbyService actually does the work.
Open the DerbyService.svc.cs fi le and replace the existing code with the following code:

using System.Collections.Generic;
using System.Linq;
using System.ServiceModel.Web;

namespace DerbyNamesService
public class DerbyNames : IDerbyNames
public DerbyName GetNames()
//get all the names from the database.
var names = new DerbyContext().DerbyNames.ToList();
return names;

public IEnumerable Leagues()
//Get all the leagues from the database.
var leagues = new DerbyContext().Leagues.ToList();
return leagues;

c03.indd 48c03.indd 48 28/07/12 5:49 PM28/07/12 5:49 PM

Creating an Example Web Service ” 49

Previously when Visual Studio asked to rename project references, it was only referring to C# code.
The DerbyService.svc markup contains text that needs to be updated. To make the change Visual
Studio missed, right-click the DerbyService.svc fi le and select View Markup as shown in
Figure 3-6.

FIGURE 3#6: View Markup

Change the text Service=”DerbyNamesService.Service1” to Service=”DerbyNamesService
.DerbyService” to match the class renaming you performed earlier. To make the service accessible
it needs to be specifi ed in the web.config. In this context, the service endpoint is effectively a web-
site to which you connect your client code. This site will receive communications from your client
over HTTP, and return objects from your data source as text. To specify the service endpoint, insert
the following XML as a child node of the system.servicemodel node:

c03.indd 49c03.indd 49 28/07/12 5:49 PM28/07/12 5:49 PM


To make the service return XML for easy consumption by mobile devices, insert the following XML
as a child node of the behaviors node:

The fi nal web.config should look like this:

After all that work, the service is coded and confi gured. Click the solution and start debugging.
Visual Studio will launch the ASP.NET Development Server and launch the system default browser
with a URL similar to http://localhost:13610. The number is the port on which the ASP.NET
Development Server is delivering requests. Add /DerbyService.svc/PlayerNames to the end of the
URL to get the PlayerNames. Figure 3-7 shows the result in Google Chrome.

c03.indd 50c03.indd 50 28/07/12 5:49 PM28/07/12 5:49 PM

Creating an Example Web Service ” 51

With the service returning data, you can now have some fun! Using the Chrome Developer Tools will
show the service response payload is 3.07KB. You can open the Chrome Developer Tools by using the
keystroke Ctrl+Shift+I in Google Chrome. Figure 3-8 shows the Chrome Developer Tools network tab.

FIGURE 3#7: Player Names XML result

FIGURE 3#8: Chrome Developer Tools network view

c03.indd 51c03.indd 51 28/07/12 5:49 PM28/07/12 5:49 PM


An earlier section of this chapter discussed the differences in protocols. Change the protocol to
JSON and see what happens. WCF makes this change easy. Open the web.config fi le and fi nd the
webHttp node under the behavior node. Change the defaultOutgoingResponseFormat from
XML to JSON. The node should look like this:

Then rebuild the project and navigate back to the ASP.NET Development Server URL
/DerbyService.svc/PlayerNames. On my machine, Chrome developer tools show the response size
is now 2.22KB, which is a 28 percent reduction in size from the XML format. This reduction in
size will result in faster transfer times, especially for larger data services. I recommended using JSON
as the default data format and providing XML only if the requirements demand it.

The next improvement to make is getting URLs that make more sense. The URL /DerbyService
.svc/PlayerNames doesn’t look nice. A better URL would be /RollerDerby/PlayerNames.
ASP.NET routing is the easiest way to get the URL /RollerDerby/PlayerNames.

Routing is built into ASP.NET, but to get it to work with the service you need to add one reference.
Expand the DerbyNameService project node, right-click References, and select Add
Reference to bring up Add Reference dialog box. Select the .NET tab and fi nd …

error: Content is protected !!