Think Twice Before Changing your APIs

How often do you make changes to a service that actually alter the API itself? I'm sure if I asked this question to an experienced developer the answer would follow something along the lines of "You would NEVER want to do that! If you change the API, you risk breaking any applications that are consuming that service." As this danger is fairly well known, how do you guard against it?

Imagine this scenario: there is a set of web services that are being consumed by multiple web applications. The API for one of these services has been changed so that a service method that was taking a string, is now taking an integer. Unfortunately, this little change caused the contract surrounding the service to also change, which meant that any applications consuming it would also need to be updated. It wasn't until another application started to throw exceptions that it became clear that one had been missed.

If this was a new area of development, a contributing factor to this oversight could have been that the developer making the change might have not known that the contract they were changing was already being consumed by multiple applications. The developer might have assumed that it was OK to change the contract because the code was "very young" and it couldn't have been integrated with other applications in such a short time frame. If anything this highlights why you can’t rely on a developer to catch this as they can't be expected to know of where each service method is being used.

The fix is simple, but could this have been avoided in the first place? A simple solution would be to never alter the API of a service, ever. The problem with this is that it is still comes down to the developer to ensure that this is being followed. Remember that in my example, the service method had been only been created very recently so it's conceivable that another developer would also assume that they were dealing with the only occurrence where the service method was being consumed. Documentation and improved communications between developers would help to identify an issue, but it would still be up to the developer to notice it.

An ideal solution would be automated so that a developer would not need to be aware of how an API is being consumed. If this could be created as a set of tests that are run as part of a build process, any issues would be identified well before deployment to production. To achieve this, you would need the ability to stage the service in a test environment where you could fire off requests to verify that the API has not changed. Another possibility would be to compared the current WSDL file with a previous version to check for changes.

If you find yourself considering altering an API, be sure to take a moment to ask yourself why. Can you extend the current contract to ensure that the API will not be broken instead of changing it? In most cases, this should be the preferred course of action and making changes to the contract should only happen when there really is no other choice.

Bootstrap 3's Grid System

I have been playing with Bootstrap 3's grid system and have found it to be a very clever general purpose grid system for assisting developers with the layout of their sites. It also helps lead you to developing a responsive design which adapts to the size of the screen size it is being displayed on. To help cement these concept in, I quickly created a demo site which allowed me to view bootstraps responsive design features in action.

You can find that site here. 
Adjust the width of the page and see how the grids layout automatically adjusts with you. These adjustments go beyond shrinking the width of a column but allow you to specify different column sizes for specific view ports. This opens up lots of options for re-arranging your site to make it just as usable on a phone, tablet or laptop.

Bootstrap goes beyond just allowing you to apply different widths to a column within a grid though. It also provides you with the ability to show and hide columns based on the width of a page. This provides you with even more functionality to empower your sites responsive design.

How does Bootstrap do this? It's all through the use of CSS media query's. Media query's allow specific CSS to be applied when certain condition are met. In the case of the Bootstrap grid system, these conditions are based on the width of your page. Take a look at the Bootstrap 3's docs to get a better understanding of how this works and the grid system in general.

With CSS frameworks like Bootstrap, HTML5 Boilerplate and Pure, its getting harder and harder to NOT create a responsive site.

Using dynamic and DynamicObject in C#

Up until I came across Simple.Data, I had only used the dynamic type when unit testing controllers that returned JsonResult objects. After playing with Simple.Data and taking a look at the source code, it became clear that there was a lot more to the dynamic type than I had realized; it hadn’t occurred to me that you could use the member’s name essentially as an additional argument (thanks Jon for making me see this!). To better understand all of this, I decided to create my own limited implementation that would allow me to execute stored procedures in the same fashion. VerySimpleData is heavily based on Simple.Data and I am not trying to take any credit for the creativity of this approach. I have tried to keep my implementation as lean as possible to highlight the use and function of the dynamic type.

VerySimpleData

First of all, you can find the repository for VerySimpleData here.

I’m sure you’re familiar with how the compiler will bark at you if you make a typo and end up calling a method or setting a property that doesn’t exist. That’s static typing at work making sure that everything your code is talking about actually does exist. The dynamic type allows you to sidestep this and by-pass what would normally be resolved at compile-time and instead have it resolved dynamically at run-time. This means that you now can call methods or set property that do not exist, as long as you’re using a dynamic type. Let's start with an example of how to use VerySimpleData to highlight this.

1 2	var database = Database.WithNamedConnectionString("connectionString"); var results = database.MyStoredProcedure(Param: "something", AnotherParam: "something-else");

In line one, the connection string is supplied and a dynamic object is returned which will act as the database context. In line two, I am calling a stored procedure called "MyStoredProcedure" and passing it two parameters called "Param" and "AnotherParam"; if I wanted to execute a stored procedure with a different name and/or parameters, I would only need to change the method's name and the names of the parameters that are being supplied:

var results = database.AnotherStoredProcedure(DifferentParam: "something-different");

Looking Under the Hood:

The entry point to VerySimpleData is through one of the static methods on the Database class:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

public static class Database { public static dynamic WithNamedConnectionString(string name) { var connectionStringSettings = ConfigurationManager.ConnectionStrings[name]; if (connectionStringSettings == null) { throw new ArgumentException("No connection string found for: " + name); } return WithConnectionString(connectionStringSettings.ConnectionString); } public static dynamic WithConnectionString(string connectionString) { IDatabase database = new SqlServerDatabase(connectionString); var dynamicContext = new DatabaseContext(database); return dynamicContext; } }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

public class DatabaseContext : DynamicObject { private readonly IDatabase Database; public DatabaseContext(IDatabase database) { Database = database; } public override bool TryInvokeMember(InvokeMemberBinder binder, object[] args, out object result) { if (binder.CallInfo.ArgumentCount != args.Length) { result = false; return false; } var procedureName = binder.Name; var parameters = binder.CallInfo.ArgumentNames.Zip(args, (s, i) => new { s, i }) .ToDictionary(item => item.s, item => item.i); result = Database.ExecuteStoredProcedure(procedureName, parameters); return true; } }

An instance of DatabaseContext is returned from the Database static class as a dynamic type when either WithNamedConnectionString() or WithConnectionString() is called. The key to this class is that it inherits from DynamicObject. DynamicObject provides the ability to interact with any of the members that are executed/set on the dynamic type by overriding the base implementation:

TryInvokeMember is invoked whenever a method is called on the dynamic object. By providing your own override of this, you can control what will happen. The example in DatabaseContext.cs is very simple. First there is a check that the argument count matches the number of arguments that were supplied. From a quick inspection, the InvokeMemberBinder appears to contains meta data/semantics about the invoked member (e.g. the names of the arguments, the name of the member being invoked) whereas the values themselves are contained on the args array. It is important to note here that the “out” result parameter holds the object that will be returned when this member is invoked; the returned Boolean for TryInvokeMember indicates if the operation was successful or not. Returning false causes a Microsoft.CSharp.RuntimeBinder.RuntimeBinderException to be thrown. This pattern is the same for all the Try[…] overrides exposed from inheriting from DynamicObject.

My implementation assumes that the name of the invoked member will match the stored procedure’s name (line 19) and that the names of the arguments will match the procedure’s parameters (lines 20-21). Calling the ExecuteStoredProcudure method (line 23) fires off the ADO.NET code that talks to the database and it should be no surprise that this returns a dynamic object as the result could be a single value, a single record, a set of records or nothing at all.

If there’s only one row and multiple columns, this will be returned as a VerySimpleDataRecord:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

public class VerySimpleDataRecord : DynamicObject { private readonly Dictionary<string, object> _data; public VerySimpleDataRecord() :this(new Dictionary<string, object>()) { } public VerySimpleDataRecord(Dictionary<string, object> data) { _data = data; } public override bool TryGetMember(GetMemberBinder binder, out object result) { if (_data.ContainsKey(binder.Name)) { result = _data[binder.Name]; return true; } return base.TryGetMember(binder, out result); } public override bool TrySetMember(SetMemberBinder binder, object value) { _data[binder.Name] = value; return true; } public int ColumnCount { get { return _data.Count; } } }

This is constructed using a dictionary collection where the key-value pairs comprise of the column name and the data that was held in that column. The TryGetMember override is invoked when performing a property get operation on the dynamic object; if there is a key in the dictionary collection that matches the property’s name, it is returned.

The final scenario is where there are multiple rows with one or more columns. In this case, a collection of data will be returned that is packaged in a way that make it enumerable:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

public class VerySimpleDataRecordSet : DynamicObject, IEnumerable { private readonly IList<VerySimpleDataRecord> _data; public VerySimpleDataRecordSet() : this(new List<VerySimpleDataRecord>()) { } public VerySimpleDataRecordSet(IList<VerySimpleDataRecord> data) { _data = data; } public override bool TryGetIndex(GetIndexBinder binder, object[] indexes, out object result) { if (indexes.Length == 1 && indexes[0].GetType() == typeof(int)) { result = _data[(int)indexes[0]]; return true; } result = false; return false; } public int Count { get { return _data.Count; } } public IEnumerator GetEnumerator() { return _data.GetEnumerator(); } }

A VerySimpleDataRecordSet is initialized by supplying a collection of VerySimpleDataRecords. Like the dictionary collection in the VerySimpleDataRecord, this is stored internally. VerySimpleDataRecordSet also inherits from DynamicObject that provides the TryGetIndex override. When this is invoked, the supplied index value is first validated and if it passes, the appropriate VerySimpleDataRecord is retrieved from the internal collection and returned. The ability to enumerate the VerySimpleDataRecordSet is achieved by implementing IEnumerable: the GetEnumerator method exposes the internal collection’s IEnumerator.

I have only touched a few of the method overrides that are available through DynamicObject mainly to do with getting and returning data. There are other operations to do with setting values and performing conversions that would be worth exploring.

SQL - Beyond the standard ORDER BY ASC / DESC

Recently at work a request came in from a user to update an existing report so it applied a specific order to the reported data. Previously the report ordered items alphabetically by Class and then Model, however, this was no longer suitable and a non-alphabetical ordering was required. 
Initially when I read this requirement I thought “Oh heck, how am I going to do this as it’s no longer in alphabetical order?”. As is often the case, the solution was simpler than expected.
I have created a simplified representation of the data in use to illustrate the technique I used to accomplish the custom sort order below.

User Requirement:
Order products in the following Class order
R-Class
ZA-Class
T-Class
G-Class
J-Class

As discussed earlier, this is not in alphabetical order so the following SQL statement will not produce the required result:

SELECT Model, Class
FROM Products
ORDER BY Class, Model

As we need to apply a specific order, we can accomplish this by introducing an additional numeric field into the result set which is solely used for ordering the results. This additional field can be produced by using a CASE WHEN statement to determine the correct numeric value to ensure the correct ordering is applied.

SELECT Model
 , Class
 , CASE
  WHEN Class = 'R-Class' THEN 1
  WHEN Class = 'ZA-Class' THEN 2
  WHEN Class = 'T-Class' THEN 3
  WHEN Class = 'G-Class' THEN 4 
  WHEN Class = 'J-Class' THEN 5      
 END AS ProductClassOrdering
FROM Products
ORDER BY ProductClassOrdering, Model

The ProductClassOrdering field will contain a numeric value which can be used as part of the ORDER BY clause to ensure the users custom ordering is applied.

Boom! This technique creates the desired result but it also introduces the use of an interesting technique: creating a field dynamically as part of your result set. It can be very easy to believe a SELECT statement can only select static data from a table (I will admit I was guilty of this belief when I first learnt SQL) but this is not true. If you start viewing each select value as a piece of data which can be generated by other means within the SQL languages constraints, you will find a whole new range of querying options available to you (sub-selects, logic to determine a value, additional filtering to name a few). 

However, a word of warning is needed. With these additional SQL powers comes great responsibility which can be summarized in a single word: performance. Keep one eye on the performance of your query when introducing additional SQL statements into the SELECT portion of your query as you can inadvertently introduce performance bottle necks into your query. 

Have a play and start flexing those SQL muscles a little more.

Development Environment Revolution 2.0

Looking back, my home development setup has gone through a couple of revolutions over the years. These revolutions have resulted in some drastic changes in my home development activities.

It all started with the desktop PC - Big, bulky and fixed to one location. Developing at home often felt like a chore as you were glued to a desk usually placed in a room out of the way.

Revolution 1 - The laptop.
It was brilliant not having to be sat at a desk when developing / studying in my free time. Being able to be sat in the front room instead of stuck at a desk was a game changer for me. It made it feel a lot less like work. However, originally laptops which are desktop replacements were bricks and difficult to pick up and walk around with. You also needed some sort of tray to help keep them well ventilated underneath plus forget taking it anywhere with you unless you are prepared for a mini workout. Things are much better these days with the advent of the ultra book. I would argue that the form factor of a laptop (screen physically attached to a keyboard) is not ideal for all use cases as there are times where you do not really need a keyboard - reading an ebook or browsing the web for instance. A good move forwards but still not quite perfect.

Revolution 2 - The Tablet.
You can truly develop anywhere. In bed, in the back garden, in the car, on the train or bus. I choose to go with an 11 inch Atom powered tab. A lot of people who I have told about this have said, "Hey, you must have the i5!?" Nope - Just the Atom processor option and it's more than capable. "Can you work on such a small screen?" Yep! I can have Visual Studio open on half the screen (drop the text size 8pt and you are rocking) and a Pluralsight video / internet browser running on the other half with a workable amount of development real-estate on offer. 
I find it helps encourage me to dive in and do some coding / studying whenever I have a few moments spare as it starts up so fast compared to my previous laptops (5 second to loading up Windows - 10 seconds if you want to be coding in Visual Studio).
I would recommend getting a detachable keyboard for your tab as it will make a huge difference to your development experience - If it has an additional battery built in, all the better! It is also nice having the option of disconnecting the keyboard if you only want to use the tab for reading / browsing.
I will admit, for heavy lifting development work you may need something a bit more beefier but with cloud storage, compute and persistence options becoming much more cheaper to access, there are plenty of other options available. (Free on Azure with an MSDN license)
I dare you, take the plunge and get yourself a latest generation Windows tab as your home development environment and tell me it has not helped revolutionized the way you code / study at home.

Using MongoDB with ASP.NET MVC (Pluralsight)

I have recently finished watching the Pluralsight course on Using MongoDB with ASP.NET MVC. I have been intending to look more into NoSQL for months now but have not got around to it. This course was the perfect excuse to do so!

The course starts by briefly introducing you to MongoDB and then swiftly shows you how to integrate it into an MVC application. It takes you through CRUD operations using Mongo as the data store then shows you GridFS (the file store for MongoDB) and the new aggregation pipeline model.

I was really impressed with the course (to the extent I decided to blog about it!). In the space of a few hours I went from knowing very little about a technology to being confident about how to utilize it in a project. Wes McClure is a first rate presenter who keeps you engaged through the course, supplying clear explanations and useful information for future proofing your Mongo projects. He also has a very interesting blog which is worth looking at. It's full of good advice and issues he has encountered in the real world.

This was one of my favourite Pluralsight course formats where you are able to code along to the course and end up with the same end product. Granted you will need to code some of the razor views yourself but the important C# code for interacting with the Mongo driver is all on show.

Wes finishes the course with some great advice: Build something! I already have a couple of projects in mind to use with MongoDB.

Where to go from here... I will start watching Nuri Halperin course Introduction to MongoDB which Wes recommends as this will get you more familiar with the MongoDB server itself. I have also spied Seven Databases in Seven Weeks which looks like a great read to getting familiar with a wide variety of NoSQL databases. But most importantly, I will be developing something.

If you want a practical introduction to MongoDB from a Web Development perspective, this is the course for you.

The days of polygot persistence are upon us.

Looking at the Microsoft Store's Authentication

A few days ago I called the Microsoft Store about an order I had placed online. After discussing what I wanted to change, the operator explained that before she could make any updates to my account she needed to check my email address (up until this point, I had only told her my name and my order number) and that she would be sending a code to that address. After confirming my email address, I quickly signed in to my account, read the code back to her and from that moment on I was verified--it was as simple as that. Let’s break this down from a security perspective.

The traditional route of authentication during a telephone call is to ask a series of questions that only you “should” know the answers to. The problem is that this isn’t always the case and these answers are generally easily discoverable: Google can help with answering what year someone got married in or what their maiden name was; if you’re OK with a little more work, you could examine the public records or even just ask the individual—I doubt most people will have a problem telling you the name of their first pet if brought up unsuspiciously in conversation.

Using a verification code bypasses all of this and places the burden of authentication solely on you having access to the email account that is registered with the Microsoft Store. The assumption is that you know the password to access your email account / that you have access to your email account. Reading the verification code back is evidence of this and satisfies that you are who you claim to be.

This becomes really interesting if the operator has no access to the code and cannot proceed without it as it presents the situation, that as well as providing authentication of you, can also provide authorization for the operator. Without the code, they would be considered unauthorized and would not be able to update an account unless they were supplied the code. This works great in preventing the operator from being coerced into updating the account, as without the code, they really have no way to do this.

I’m impressed with the ease of using a verification code sent by email and the potential it has for offering both authentication and authorization. Of course, if I was unable to access my email account at the time I called, I might have a less favorable opinion; however, an easy alternative would have been to send the code to the mobile phone that was on my account.