Fluent Essays

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 WHAT’S IN THIS CHAPTER? ! 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. WHAT IS A WEB SERVICE? 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 3 c03.indd 37c03.indd 37 28/07/12 5:49 PM28/07/12 5:49 PM 38 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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. WHAT IS A PORT? 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 http://data.stackexchange.com/stackoverflow/query/66263/ 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: http://data.stackexchange.com/stackoverflow/ atom/Users(46076). 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: http://www.google .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. WHAT IS THAT UGLY %20? 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: <script type=”text/javascript”> var url = ‘http://www.gravityworksdesign.com/ large images.aspx?folder=2012/April’; document.write(encodeURI(url)); document.write(‘<br />’); document.write(encodeURIComponent(url)); var urlCorrect = ‘http://www.gravityworksdesign.com/ large images.aspx?folder=’ var queryCorrect = ‘2012/April’; document.write(‘<br />’); document.write(encodeURI(urlCorrect) + encodeURIComponent(queryCorrect)); </script> It outputs: http://www.gravityworksdesign.com/large%20images. aspx?folder=2012/April http%3A%2F%2Fwww.gravityworksdesign.com%2Flarge%20images.aspx %3Ffolder%3D2012%2FApril http://www.gravityworksdesign.com/large%20images.aspx? folder=2012%2FApril 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 40 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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 <zipcode>48906</zipcode>, 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. WEB SERVICES LANGUAGES !FORMATS" 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: <length measurement=”inches”>5 </length>. 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: <person> <firstname>David</firstname> <lastname>Smith</lastname> </person> 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: <person firstname=”David” lastname=”Smith” /> 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: <person><age>30</age></person> would better be displayed on a web page like this: <span>Age:30</span>. 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. <xsl:template match=”/”> <xsl:for-each select=”person”> <span>Age:<xsl:value-of select=”age”/></span> </xsl:for-each> </xsl:template> XQuery 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 42 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES <order> <item price=”50” currency=”USD” name=”metal gear” /> <item price=”25” currency=”USD” name=”plastic gear” /> </order> The following XQuery returns the sum: sum(doc(‘orders.xml’)/order/item/@price) For testing or learning XQuery, a handy online sandbox is: http://basex.org/products/ live-demo/. 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. CREATING AN EXAMPLE WEB SERVICE 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 http://www.wrox.com) 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 44 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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 node. 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 46 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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 { [Table] public class DerbyNames { [Column(IsPrimaryKey = true)] public int DerbyNameId; [Column] public string Name; [Column] 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; [Column] public DateTime? DateAdded; [Column] 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 { [Table] public class Leagues { [Column(IsPrimaryKey=true)] public int LeagueId; [Column] public string LeagueName; [Column] public string URL; [Column] public string StateProvince; [Column] 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> DerbyNames; public Table<Leagues> 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 48 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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 { [ServiceContract] public interface IDerbyService { [OperationContract] public IEnumerable<DerbyNames> PlayerNames(); [OperationContract] public IEnumerable<Leagues> 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 { [WebGet(UriTemplate=”/PlayerNames”)] public DerbyName GetNames() { //get all the names from the database. var names = new DerbyContext().DerbyNames.ToList(); return names; } [WebGet(UriTemplate=”/Leagues”)] public IEnumerable<Leagues> 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: <services> <service name=”DerbyNamesService.DerbyService”> <endpoint binding=”webHttpBinding” contract=”DerbyNamesService.IDerbyService”/> </service> </services> c03.indd 49c03.indd 49 28/07/12 5:49 PM28/07/12 5:49 PM 50 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES To make the service return XML for easy consumption by mobile devices, insert the following XML as a child node of the behaviors node: <endpointBehaviors> <behavior> <webHttp defaultOutgoingResponseFormat=”Xml”/> </behavior> </endpointBehaviors> The fi nal web.config should look like this: <?xml version=”1.0”?> <configuration> <system.web> <compilation debug=”true” targetFramework=”4.0” /> </system.web> <system.serviceModel> <services> <service name=”DerbyNamesService.DerbyService”> <endpoint binding=”webHttpBinding” contract=”DerbyNamesService.IDerbyService”/> </service> </services> <behaviors> <endpointBehaviors> <behavior> <webHttp defaultOutgoingResponseFormat=”Xml”/> </behavior> </endpointBehaviors> <serviceBehaviors> <behavior> <serviceMetadata httpGetEnabled=”true”/> <serviceDebug includeExceptionDetailInFaults=”false”/> </behavior> </serviceBehaviors> </behaviors> <serviceHostingEnvironment multipleSiteBindingsEnabled=”true” /> </system.serviceModel> <system.webServer> <modules runAllManagedModulesForAllRequests=”true”/> </system.webServer> </configuration> 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 52 " CHAPTER 3 CREATING CONSUMABLE WEB SERVICES FOR MOBILE DEVICES 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: <webHttp defaultOutgoingResponseFormat=”Json”/> 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 …