2005 2006 2007 2008 2009 2010 2011 2015 2016 aspnet azure csharp debugging exceptions firefox javascriptajax linux llblgen powershell projects python security services silverlight training videos wcf wpf xag xhtmlcss

ESV Bible Web Service Client for .NET 3.5

A while back, the guys over at the ESV Bible web site announced their new REST-based interface to replace their old SOAP interface.  This new interface provides the same functionality as the old, but allows for 5,000 queries per day instead of 500 previously and is based on REST architectural principles.  Because the service is fundamentally chatty, it made sense to switch to REST.  In the context of a Bible web service, it's hard to justify a 200-byte XML message when your actual request is 6 bytes ("John 1").  Also, because the method call is in the URI, the entire call is simplified all the more.

For those of you who are completely unfamiliar with REST interfaces, all you really need to know is that it's a resource (or noun) based architecture.  That is to say instead of calling, for example, a "GetItem" method, you simply access an "item" entity.  You access what the thing is, not what the thing does; kind of a web-based reversal of encapsulation.  In other words, instead of giving a server a command (a verb), you are accessing the resource directly (a noun).  There's obviously more to REST than this and you can get more information from this nice article titled "Building Web Services the REST Way".

RESTful architecture really is a nice way to telling a system what you want, not how to get it.  This is really the point of framework design and abstraction in general.  In light of this it's obvious to see that, as awesome as REST is, it's not how .NET developers want to think when working working on a project.  When I'm working with something I want to focus on the object at hand, not on the URLs and parameters.  For this reason, I built a .NET 3.5 framework that allows easy and efficient access to the new ESV Bible REST web service.  Here are some samples of how to use it:

Here's a simple passage query returning HTML data:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );
String output = service.PassageQuery("Galatians 3:11");

With the flip of a switch you can turn it into plain text:

ESVBibleServiceV2 service = new ESVBibleServiceV2(OutputFormat.PlainText);
String output = service.PassageQuery("Galatians 3:11");

For more flexibility, you may use the provided parameter objects.  Using these in C# 3.0 is seamless thanks to object initializers:

PassageQueryParameters pqp = new PassageQueryParameters( ) { Passage = "John 14:6" };
ESVBibleServiceV2 service = new ESVBibleServiceV2(new PlainTextSettings( )
{
    LineLength = 100,
    Timeout = 30
});
String output = service.PassageQuery(pqp);

Here is a simple sample of accessing the verse of the day (in HTML without the audio link -- optional settings):

ESVBibleServiceV2 service = new ESVBibleServiceV2(new HtmlOutputSettings( )
{
    IncludeAudioLink = false
});
String output = service.DailyVerse( );

You can also access various reading plans via the provided .NET enumeration:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );
String output = service.ReadingPlanQuery(new ReadingPlanQueryParameters( )
{
    ReadingPlan = ReadingPlan.EveryDayInTheWord
});

Searching is also streamlined:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );
String output = service.Query("Justified");

Here is a length example showing how you can use the QueryInfoAsObject method to get information about a query as a strongly-type object:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );
QueryInfoData result = service.QueryInfoAsObject("Samuel");

Console.WriteLine(result.QueryType);
Console.WriteLine("----------------------");
if (result.QueryType == QueryType.Passage) {
    Console.WriteLine("Passage: " + result.Readable);
    Console.WriteLine("Complete Chapter?: " + result.IsCompleteChapter);
    if (result.AlternateQueryType != QueryType.None) {
        Console.WriteLine(String.Format("Alternate: , ", result.AlternateQueryType, result.AlternateResultCount));
    }
}

if (result.HasWarnings) {
    foreach (Warning w in result.Warnings) {
        Console.WriteLine(String.Format(": ", w.Code, w.Readable));
    }
}

Here is the output:

QueryInfoAsObject Example Output

For more advanced users, the Crossway XML format is also available:

ESVBibleServiceV2 service = new ESVBibleServiceV2(new CrosswayXmlVersion10Settings( )
{
    IncludeWordIds = true,
    IncludeXmlDeclaration = true
});
String output = service.PassageQuery(new PassageQueryParameters( )
{
    Passage = "Galatians 3"
});
Console.WriteLine(output);

That same XML data is also retrievable as an XmlDocument for pure XML interaction:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );
XmlDocument output = service.PassageQueryAsXmlDocument("Galatians 3");

For more flexible XML interaction, you may use XPath:

ESVBibleServiceV2 service = new ESVBibleServiceV2( );

String output = service.PassageQueryValueViaXPath(new PassageQueryParameters( )
{
    Passage = "Gal 3:4-5",
    XPath = "//crossway-bible/passage/surrounding-chapters/current"
});

Sometimes, however, you will want more than one result from XPath:

String[] output = service.PassageQueryValueViaXPathMulti(new PassageQueryParameters( )
{
    Passage = "Gal 3:4-5",
    XPathSet = new[]
    {
        "//crossway-bible/passage/surrounding-chapters/previous",
        "//crossway-bible/passage/surrounding-chapters/next"                
    }
});

Here's what the result looks like the debugger:

XPathSet Example Output

I've also copied the documentation for functions and parameters into the .NET XML comments, so you can quickly and easily see what a certain function or parameter does and it's default:

ESVBibleServiceXmlComment

The new API uses your existing ESV Bible Web Service access key.  To use this key in this framework you simply add an element called ESVBibleServiceKey to the addSettings in your configuration file (a sample is provided with the framework).  You may also set it in any one of the parameter objects (i.e. PassageQueryParameters, QueryParameters, etc...), which override the key in the configuration file.  Per the API, you can use TEST for testing and IP for for general purpose queries.

Lastly, I would like to mention that this framework minimizes traffic by only sending options that deviate from defaults. So, for example, if you set IncludeWordIds to false and IncludeXmlDeclaration to true, only the IncludeXmlDeclaration value will be sent over the wire since IncludeWordIds is false by default.

You can access this ESV Bible Web Service 2.0 framework on CodePlex at the address in the links section.  Enjoy!

Links

Prototype and Scriptaculous Book

Today I noticed the book "Prototype and script.aculo.us: You never knew JavaScript could do this!" and while you do not need a book to learn P&S, this book will definitely induce a good 6 months to a year of experience into your skill set.  The book is available on Amazon in print or on the book's website in PDF format.

If you only want to know the basics of P&S, then you'll be fine with looking over the Prototype documentation and script.aculo.us samples.  However, regardless of how deep you want to go, you should definitely check out the freely available source code for the book available on the book's website.

As always, let the tools do the work, but don't rely on them for everything.  It's critically important that you understand AJAX developer from a deep mechanical level before you start using JavaScript or AJAX frameworks.  If you aren't well-versed in JavaScript and AJAX development, then I highly recommend AdvancED DOM Scripting: Dynamic Web Design Techniques by Jeffery Sambell.

Related Links

Accelerated Language Learning (Timothy Ferris)

Many years ago I wrote a paper on accelerated learning and experience induction.  This paper explains how I induce weeks of experience in days, months of experience in weeks, and years of experience in months and how to dramatically learn new technologies with little to no investment.  I know people who have worked in a field for 4 years, but only have 6 months worth of skill (usually VB developers -seriously).  I also know people who have worked for 6 months, but have over 4 years of skill (usually Linux geeks; paradoxically, VB developers usually are quicker to learn .NET basics than PHP developers, though they usually switch places in more advanced studies.)  How can anyone expect to gain skill by doing the exact same job for 4 years (e.g. building database driven interfaces, cleaning data, writing reports)?  Obviously, calendar-years of experience is not directly related to skill-years of experience.  As it turns out, my learning techniques are not uncommon.

Today, author Timothy Ferris (Four Hour Work Week) posted a blog entry about how he learns languages in an incredibly short timeframe.  His post was fascinating to me for many reasons, one of them being that his first step is as follows: "Before you invest (or waste) hundreds and thousands of hours on a language, you should deconstruct it."  This is the same first step in my accelerated learning method.  Apparently I was on to something!  In his deconstruction method, he asks a few key questions and does some component and paradigm comparisons to give you some idea of the language scope and of its difficulty.  Based on what you learn from the deconstruction, you should have a good idea of what the language entails.

In my learning system, I refer to this deconstruction as "learning the shell", which is followed by "learning the foundations", then "learning the specifics" -- Shell, Foundations, Specifics -- my SFS (pronounced "sifs") method.  The method exploits Pareto's Law, allowing you to learn 20% of the technology at first to give you 80% of the return.  That's MUCH more than what most so-called "experts" have anyhow!  As it turns out, Timothy Ferris uses Pareto's Law in his language learning as well.  You can hear about this in his interview with my other role model, Scott Hanselman.

For more information on Timothy Ferris' other life-optimization work, check out his book The Four Hour Work Week and his blog.

Related Links

Web Application Security Presentation

Today I found a really nice web application security presentation by Joe Walker.  Honestly, almost none of it is common sense and I would therefore encourage all web developers to check this out.  Also on the same page as the presentation are a number of very good AJAX security links like the XSS (Cross Site Scripting) cheat sheet.

BTW, this type of stuff is touched on in the Brainbench AJAX exam.

Links

Prototype and Scriptaculous

OK, it's time that I come out with it: I've switch to using the prototype and script.aculo.us ("scriptaculous") JavaScript/AJAX frameworks. For the longest time I've sworn my allegiance to manual AJAX/DOM manipulation as I've always found it to be the absolute most powerful way to get the job done correctly, but as it turns out prototype/scriptaculous provide an incredible level of simplification without taking any of your power from you.  It's the ONLY AJAX framework I found that didn't suck.  Though I'm a .NET developer, I can't  the Microsoft ASP.NET AJAX ("Atlas") extensions.  Except for it's awesome web service handling, which I use all the time, it's a slap in the face of AJAX development. It's bulky with hard to read source code that has an incredibly low usability.  It seems to be the opposite of the beauty of C# and .NET in general.  With those technologies, everything just falls together without ever needing to read a thing (assuming you are a qualified web professional who understands the foundational concepts of the system). Sure, you have to look up stuff in the docs, but you don't have to pour over book on the topic to be productive.  The same can be said for prototype and scriptaculous.

So, what is this thing? Actually are two frameworks, one, prototype, is a single JavaScript file and the other, scriptaculous, is a series of JavaScript files. Prototype is a foundational JavaScript framework that simplifies the existing client-side JavaScript API into something much more intuitive and that's also widely cross browser compatible. Finally! Cross browser compatibility without needing to support it!  That means we no longer have to do a zillion tests to see how we are supposed to get an element's height. I can just simply call $('box').getHeight( ) and be done with it! Prototype has classes (types) for Arrays (which including a very powerful each( ) function-- similar to .NET's ForEach method, Elements (which allows you to modify style, add classes, get ALL descendants -- not just the children), Events (instead of trying to test for addEventListener or attachEvent, just use Event.observe!), and classes for a ton of other things. To put it simply: prototype gives you a new client-side API. The source code is also incredibly each to read. It's just the same stuff most of us have already written, but now we don't have to support it.  If we build our applications on prototype, some one else has pre-tested a BUNCH of our system for us!

Scriptaculous is a different beast entirely. While prototype is a new general client-side API, scriptaculous goes more specifically into dynamics. For example, it allows you to turn a normal list into a sortable list with ONE line of JavaScript.  ONE.  Uno.  Eins.  It also allows you to Turn one div set into a series of draggable elements (products?) and another set of divs into containers that the items can go to (shopping carts?) There are also a very nice set of pre-built animations as well as other common things like an autocompleting textbox and an in-place editable label. These are I've normally built manually, but can use them without micro-managing code.  Code by subtraction RULES!  Scriptaculous is also VERY flexible. Everything you can do in scriptaculous is extremely customizable thanks to JavaScript's flexible dynamic object syntax and native higher-order function capabilities. That means, for example, that when you create a sortable list you can control exactly how it can scroll and set callback functions all in the same simple line of code. Also, note that scriptaculous uses prototype's API for it's lower-level functionality. This is why you will often see the two products named together, like the various books written on "prototype and scriptaculous".

What about some samples? Well, Prototype and Scriptaculous are both SO simple to work with I have absolutely no idea how someone can write a book on them. I go to various Borders bookstores about every day (it's my office), so I get to see many different books. When I flip through the prototype/scriptaculous books I get very confused. How can someone take hundreds of pages to write something that could be said in 20 or 30?  Verbosity sucks (yeah I know... look who's talking).  These framework are insultingly simple to work with.

Here are a few very quick samples.  For better samples, just download scriptaculous and view extremely well-documented prototype API online.

Prototype

Want to make a simple AJAX request?

new Ajax.Request('/service/', { 
  method: 'get', 
  onSuccess: function(t) { 
    alert(t.responseText); 
  }
}); 

No XmlHttpRequest object, no COM objects, nothing!

How about updating the content of an element?

Using this element...

<div id="myText"></div> 

...with this JavaScript...

$('myText').update('this is the new text'); 

... you get an updated element!  As you can see, it even uses the typical $ syntax (in addition to $$, $A, $F, $H, $R, and $w syntax!) Just look at the examples in the Prototype API to see more.  You will be shocked to see how easy it is to walk to DOM tree now.  You will also be amazed at how much easier arrays are to manipulate.

Script.aculo.us

Using this XHTML structure...

<ul id="greek">
<li>Alpha</li>
<li>Beta</li>
<li>Gamma</li>
<li>Delta</li>
</ul>

...with this SINGLE line of JavaScript...

Sortable.create('greek');

..., you have a sorting list (try that out-- you will also notice some nice spring-back animations happening too!)

Need callback when sort is completed? (well of course you do!)  Just give the <li> elements a patterned ID ('listid_count')... 
 

<ul id="greek">
<li id="greek_1">Alpha</li>
<li id="greek_2">Beta</li>
<li id="greek_3">Gamma</li>
<li id="greek_4">Delta</li>
</ul>

...and add a function callback and you're done.

Sortable.create('greek', {
  onUpdate: function( ){ 
    alert('something happened');
  } 
});

Ooooooooooooooo scary. IT'S THAT EASY! You don't need a book. Just use the docs and samples online.

Here's another one: want to move an item from one list to another?

Just use these elements...

<ul id="greek">
<li id="greek_1">Alpha</li>
<li id="greek_2">Beta</li>
<li id="greek_3">Gamma</li>
<li id="greek_4">Delta</li>
</ul>
<ul id="hebrew">
<li id="hebrew_1">Aleph</li>
<li id="hebrew_2">Bet</li>
<li id="hebrew_3">Gimmel</li>
<li id="hebrew_4">Dalet</li>
</ul> 

... with this JavaScript.

Sortable.create('greek', { containment: ['greek', 'hebrew'] });
Sortable.create('hebrew', { containment: ['greek', 'hebrew'] });

Want to save the entire state of a list?

var state = Sortable.serialize('greek');

Couple that with the simple prototype Ajax.Request call and you can very quickly save the state of your dynamic application.

Now close your jaw and stop drooling.  I haven't even shown the drag-n-drop, animations, or visual effects that Scriptaculous provides.  Also, get this: it's all FREE. Just go get it at the links below. Be sure to look over the docs a few times to get some more examples of the prototype functionality and scriptaculous usage. I've thrown out A LOT of my own code without looking back now that I have these amazing frameworks. This is good stuff.

AdvancED DOM Scripting Book

Oh, and as always... be very certain that you know your AJAX before you do this.  I know it goes without saying that you need to be a qualified professional to use powerful tools, but some amateurs and hobbyists (and men who get a hand crushed trying to fix the wash machine) think "Hey! This tool can do it for me! I don't need to know how it works!".  So, make sure you understand the three pillars of AJAX (AJAX Communication, Browser Dynamics, and Modern JavaScript) before you even bother with the powerful frameworks or else you will by flying blind.  Basically, if you can't recreate the Prototype framework (very easy to read code!), you shouldn't be using any JavaScript/AJAX framework.  If you aren't familiar with AJAX Communication, Browser Dynamics, or Modern JavaScript. Check out Jeffery Sambell's amazing book AdvancED DOM Scripting   It's an amazing guide covers all the prerequisites for AJAX development from service communication to DOM manipulation to CSS alteration.  It's amazing.  Even if you're an AJAX expert, buy this book!

Links

Powered by
Python / Django / Elasticsearch / Azure / Nginx / CentOS 7

Mini-icons are part of the Silk Icons set of icons at famfamfam.com