Book Review: Drupal Web Services

Michael J. Ross writes "In the evolution of the Web, one of the most significant improvements was the general transition from static websites based only upon HTML, to dynamic websites based upon scripting languages. But even then, each website was much like a silo, with no publication of content beyond the pages provided on the site itself. That all began to change with content syndication through RSS, and the development of web application APIs. Nowadays, a growing number of organizations are publishing online content through web services, as well as consuming content published by others. These sites can be built using Drupal, an open-source content management system (CMS). Drupal Web Services, a book authored by Trevor James, aims to help web programmers do that sort of development." Read below for the rest of Michael's review.

Drupal Web Services
author	Trevor James
pages	320 pages
publisher	Packt Publishing
rating	8/10
reviewer	Michael J. Ross
ISBN	978-1849510981
summary	A guide to connecting a Drupal website to external services.

Released by Packt Publishing on 24 December 2010, under the ISBN 978-1849510981, this book is the only one currently on the market that focuses on how to "integrate social and multimedia web services and applications with your Drupal Web site" (to quote from the book's marketing copy). Its 320 pages are organized into a dozen chapters and one appendix. The publisher makes available a web page with a description of the book, its table of contents, and a sample chapter (Chapter 9, "Twitter and Drupal"). The page notes that readers do not have to have any programming expertise, but should be familiar with the use and administration of a Drupal site. The book covers Drupal 6, as version 7 had not been finalized and released until a couple weeks after the book's publication. Visitors can also read the reported errata (of which there are none, as of this writing), and download the example code used in nine of the chapters. (This review is based on a print copy the publisher kindly provided. An e-book version is also available.)

The first chapter serves as an introduction to web services at a high level, including remote procedure calls (RPC), as well as some of the most commonly used protocols, with some focus on Representational State Transfer (REST). The author then gives several examples of web services that can be consumed by a Drupal website, and others where the site provides the service. This material is a fine overview, although nonprogrammers may be scared away unnecessarily by the inclusion of coding details, such as the Mollom service requests. Also, the writing style is rather repetitious in some places, e.g., "it will cost you to sign up for it. It's not a free service" (page 16). More amusingly, on page 9, the author states, "The computer that contains the application [] can be anywhere in the world," and then adds, "It could be sitting on a server in the US, Europe, Asia, South America, or somewhere else" — as if any reader might be unfamiliar with the major regions of the world. On the other hand, some readers may appreciate a slower narrative pace. Yet most troubling of all is the claim (on page 12) that many of the popular web applications are based on PHP (as is Drupal), and thus we have the advantage of "a common programming language." That contradicts the whole point of web services, namely, sharing data and other resources among websites regardless of those sites' underlying technologies. A typical web service does not transmit source code, hence its language is irrelevant, as is the language of any other website with which it interacts. (This so-called advantage is never substantiated, or even explained, anywhere in the book.)

The next four chapters take a detailed look at how a Drupal website can consume third-party web services, beginning with the use of Simple Object Access Protocol (SOAP) in general, and two contributed modules in particular (the SOAP Client module, and the FedEx Shipping Quotes module — which depends upon the Ubercart shopping cart module). The discussion of the topics is complete and straightforward, with screenshots as needed to show what administrative forms need to be filled out by anyone following the instructions. This approach is followed in the subsequent three chapters, which show how to use the web services of Flickr, Amazon, CDN2, and Kaltura. Chapter 5 discusses video, and thus its coverage of the Media:Flickr module for turning photos into slideshows should have been placed in the third chapter, which was devoted to Flickr.

Chapter 6, which focuses on the use of the Services module, essentially begins the second part of the book, because the reader starts learning how to make a site provide web services, i.e., no longer acting solely as a client — although there are some cases where web services are consumed at the same time as they are offered to outside clients. The Services module works in conjunction with other Drupal modules that implement web service methods (SOAP, REST, JSON, etc.). All of the examples are helpful, but the photo_service_all() function on page 136 is odd, because the author states that it returns an array of nodes, but the code suggests instead that it returns the nodes' content, concatenated together as a string. Similar to the first part of the book, the remaining chapters in the second part focus on specific web services: CAPTCHA, reCAPTCHA, TypePad, Mollom, Google Docs, Twitter, LinkedIn, and Facebook. Chapter 12 explores the authentication services OpenID and OAuth, but strangely ends by stating that it is time to test the OAuth connection, with no explanation as to how to do so. Incidentally, to Drupal administrators unfamiliar with the use of the Views module, the first sentence on page 205 will likely be quite confusing, because it conflates fields with filters. (The phrase "filters in" should be replaced by "includes" or "uses.") Also perplexing is that on pages 209-210, the author advises the use of "http://" instead of "www." in short URLs, but two pages later the results show the opposite. The phrase "FBML is now considered by Facebook" is baffling; considered what by Facebook? Lastly, the author states that OAuth will be tested with Digg (page 259), but that is not covered.

The book's sole appendix briefly presents each of the major contributed modules used, organized by chapter. For each module, there is a brief summary of its purpose, the current maintainers and version, and links to its project page and usage statistics. Two passages in Chapters 7 and 8 suggest that the book's appendix was not finished as intended: The author states (page 150), "I've attached the code for the recaptchalib.php file as an appendix in this book," but that does not appear to be the case — which is fortunate, because the book should not be made longer by including source code that is easily available to the reader. On page 177, we are told that the appendix explains how to install Acquia Drupal, but it does not.

The figures used in the book are, for the most part, quite handy, to see the results — especially for the reader following along who does not want to implement all of the instructions. However, the first screenshot on page 103 and the second screenshot on page 114, were incorrectly swapped for one another, and thus do not match the respective descriptions in the text.

Even though the writing quality of this title is a bit better than the typical programming book nowadays, there are some problems. Countless verbs are prefixed by the (useless) phrase "go ahead and" — to the extent that the reader will be sick of it by the time he reaches the end of the book. Occasionally the phrasing is rather puzzling. For instance, on page 131, the screenshot shows that a list of field names should be separated by commas, with no spaces. The author's explanation is "Make sure to not avoid spaces"

There are a couple instances in the book where critical configuration settings are not introduced or explained until after the reader is told that he will see results from following all of the earlier steps (which include most of the configuration settings). For example, in Chapter 4, the author instructs the reader to install the Amazon, CCK, and Features modules, and test everything using the Amazon Examples module. Pages later — possibly after the reader has been frustrated in trying to get the example scenario to work — he is told how to configure the Features module to enable the Amazon Examples features.

As with most Packt titles, the copyediting is quite poor, with inconsistent punctuation and plenty of errata that should have been caught in the production process: "and and" (on the "About the author" page), "at [the] time" (page 3), "try and access" (page 11; should read "try to access"), "a RPC" (page 15), "[a] server API" (18), "APress" (22), "is a not a" (25), "delivery Information" (43), "on how" (70), "to to" (89), "you [c]an" (94), "extention" (97), "the the" (106), "user Drupal user" (184), "se e" (198), "CMS(" (232), "both the methods" (252), "Try it both methods" (258), and "sign [in] to" (259). There are countless places where the term "the" is missing, e.g., twice on page 16. The menu path delimiter used is sometimes ">" (e.g., page 226), but usually "|," which makes each menu path look too much like page links in a footer.

However, the main problem with the narrative is that the author repeats information — in most cases not just once, but numerous times. For example, in the second chapter, we are told three times that the author will present the SOAP and FedEx shipping quotes modules. By the time the reader reaches page 33, he likely will already be tired of being told the same information. But on that page alone, the author goes over the same ground two more times. In fact, the beginning of the second paragraph sounds like a copy of the first. Compounding the problem, the author will frequently take some of the material from the main section where it is discussed, and add it to the tail end of the previous section — somewhat like a preview, but wholly unnecessary. Packt Publishing's content editors should have caught and weeded out this redundancy. Each chapter ends with a summary, which add no value and exacerbate the repetitiveness of the chapters' main content. One glaring example of redundancy, in the last chapter, is the second go-round of how to define a Twitter application, which had already been covered in Chapter 9.

Yet one advantage to repeating explanations, is that no reader will miss key instructions. This would be most advantageous to readers skimming the material at a fast pace, or anyone new to administering a Drupal website and consequently lacking in confidence. Anyone reading this book will likely be impressed by the way that the author patiently steps the reader through every process. Due to the detailed explanations, each chapter stands on its own, thereby making it possible for the reader to learn a particular topic without having to read any of the earlier chapters. This also makes the book valuable not just as the tutorial, but for reference purposes.

With clear and thorough explanations, Drupal Web Services would be an solid resource for anyone who wants to connect a Drupal-based site to any web service, including the major social media applications.

Michael J. Ross is a freelance website developer and writer.

You can purchase Drupal Web Services from amazon.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.