ASP.NET Web API

The ASP.NET Web API framework was introduced recently into ASP.NET.  I touched on it some previously at an overview level, but would like to dig in a little more at this time to show the power of having a true Web API in your product.  

Overview

From a high level, leveraging the Web API framework in ASP.NET allows you to easily build HTTP based services geared at reaching browsers, desktop or mobile clients.  By creating a responsive layer of RESTful APIs for a product, the platform immediately becomes a much more adaptable and scalable solution.  The simple act of ensuring all 'real' application logic is handled behind a RESTful API call, an inherent separation of interests is manifested, which enables a more loosely couple application at every layer.

ASP.NET Web API Infrastructure

At its base, the ASP.NET Web API mechanism is a simple adaptation of an HTTP service.  Web API can be used along with WCF, but realistically, they are two means to create virtually the same thing.  The main aspect of a Web API layer is the ability to create an API project within a given solution that allows user stories to be executed via RESTful calls to the services.  Microsoft has a great tutorial for creating a simple Web API project as an introduction to the platform.  For those familiar with MVC, this exercise should be very straightforward and easily worked through.  In fact, as you work through this, it will probably become clear that there is very little difference here than a standard MVC application.  The main difference is that Web API uses the HTTP method, not the URI path, to select the action. But, you can also use MVC-style routing in Web API if that is more your style.

Dynamism

Leveraging an API infrastructure as a service layer for you web application gives you the ability to manifest any client on any platform without recreating application intelligence. Some of the main features of Web API allow for the creation of a dynamic service layer that can interact with multiple versions of the same platform, 3rd party vendors, customer integrations and most importantly, your own application.  A strong API will have an entry point to accommodate the same list of user stories that the main presentation layer in your application presents to a user.  The API layer should handle modeling, security, extensibility and scalability.  This allows for the consistent use of application logic and business rules across multiple consuming platforms.  API/SDK layers should be manifested by version, with all historic versions co-existing.  A single set of business logic and data access logic should persist across versions of API.  This allows forward movement without backward degradation.  By adhering to the rule of the eternal public interface, this is an achievable goal.

The 'Real' API

While the main focus of this post is the ASP.NET Web API offering, I would like to make a point regarding what an API should be in my opinion.  An API should be a complete manifestation of every user story that exists in your application.  The API should be a service layer that is not the data access layer, nor is it the main business logic layer.  It is the manifestation of User Stories.  This type of layer has been called the User Story Layer and the services contained within have been called Complex Services.  This is a logical regrouping, or coupling of specific business logic tasks to create a user story.  A user story should be completely executed within its single methodological representation, including input validation, security and access validation, activity logging and return values. All manifested user story methods should assume no knowledge of requirements, modalities, system or data flow from any client executing the method. Data access and business logic should never be directly exposed to an end user, third party or otherwise.  Data access and business logic should be separated from each other as well as from the API/SDK/USL.  This enables the ability to quickly couple existing sets of logic into a new user story without having to accommodate situational elements inside the business logic layer.  For more information on building a strong SOA, see some of my previous posts here.  For a theoretical discussion of the purpose behind SOA, check this post.  A framework that has been built with this decoupled approach of singularly responsible object residing behind globally accessible services will much more easily allow for productivity items such as Continual Integration, Continual Deployment, and fully automated testing.

Your First API Client

The short answer here is that it’s your application.  A robust API should first and foremost serve all logic to your own applications.  You have to create your API and then consume it.  This ensures that all changes made are not only accounted for in the API, but are placed there with intent.  You have to eat your own dog food.  In a web development and agile deployment environment, the ability to decouple code and responsibility of objects is the best friend you will ever have.  Approach your web design with intent and long term vision for things like scalability and performance.  Understand that you need to support multiple versions of your service layer and extend your data objects over multiple versions.  A properly architected system will ensure you are able to respond to changes in your market and your market requirements much more quickly than would be the case otherwise.

IIS Issue - Ignoring default document

We were having some issues trying to get an Azure app to show the proper page by default when hitting the root domain.  We flailed around for a while and eventually someone found out that there is a known issue in Windows 7 Service Pack 1 that causes the Extensionless URL feature to interfere with the way ASP.NET parses URLs that would normally be handled by the Default Document setting.  This causes redirection to the Forms Authentication login page instead of the Default Document when the url is pointing to the root of the website.  The solution is to rewrite any requests made to the root of the website to a url that explicitly references the "defaultDocument".

Do this in the global.asx:

void Application_BeginRequest(object sender, EventArgs e)
{
    if (Request.AppRelativeCurrentExecutionFilePath == "~/")
    {
        // Get the defaultDocument filename from web.config.
        System.Xml.Linq.XDocument xDoc = 
            System.Xml.Linq.XDocument.Load(HttpContext.Current.Server.MapPath("~/Web.config"));

        string defaultDocumentName = 
            xDoc.Element("configuration")
            .Element("system.webServer")
            .Element("defaultDocument")
            .Element("files")
            .Element("add").Attribute("value").Value;

        // Rewrite the url.
        HttpContext.Current.RewritePath(defaultDocumentName);
    }
}

Hope this saves someone else some time.

ASP.NET Web API: CORS support and Attribute Based Routing Improvements

Scott Gu published an update on some ASP.NET Web API additions that look pretty exciting,  His post is available  here .and goes through some of the items that are coming in the near future to help support the Web API that was recently introduced in .NET 4.5.  one of the really nice items is the ability to use attribute based routing.  This allows you to use default values on your APIs, define custom actions, create route prefixes and support multiple versions of your API services.  It is a good read. 

iOS home screen icons for web apps

Since a lot of us are trying to create more dynamic web content for consumption on mobile devices, we find ourselves moving away from native applications and toward responsive design in web applications. One of the small items that can make these web applications feel more like the native app that users download from the iOS store is to create a proper home screen icon.  This is the icon that stays on the home screen of the iOS device when a user creates a shortcut. This is easily handled and can actually be designed for specific devices using nothing more than your markup.  This is accomplished by creating icons of differing resolutions using a standardized naming convention that will be natively referenced and leveraged by the iOS device as part of the shortcut making process.  

One of the cool things that iOS does for you is add rounded corners, shine and drop shadows to your icon in order to ensure some level of short cut consistency. All you need to do there is create you icon without making an attempt at any of those effects.  If you consider yourself a graphic artist and want to do your own effects, just append append the -precomposed keyword to the end of the file name when you create your icon.  This will instruct the iOS device to not apply the native effects it has.  The only thing left at this point is to copy the files to the root directory of your web applications domain with the following naming scheme intact.

File Name	Size	Device	iOS adds effects
apple-touch-icon.png	Any	Any	Yes
apple-touch-icon-precomposed.png	Any	Any	No
apple-touch-icon-57x57.png	57x57	Touch	Yes
apple-touch-icon-57x57-precomposed.png	57x57	Touch	No
apple-touch-icon-72x72.png	72x72	iPad	Yes
apple-touch-icon-72x72-precomposed.png	72x72	iPad	No
apple-touch-icon-114x114.png	114x114	Retina	Yes
apple-touch-icon-114x114-precomposed.png	114x114	Retina	No
apple-touch-icon-144x144.png	144x144	Retina	Yes
apple-touch-icon-144x144-precomposed.png	144x144	Retina	No

This mechanism is flexible enough to allow individual pages to set their own icons via markup as well. Here is an example of targeted icons per device with the following code added to the individual page(s).

 <link rel="apple-touch-icon" href="/icon.png"/>  
 <link rel="apple-touch-icon" href="iphone-icon.png" />  
 <link rel="apple-touch-icon" sizes="72x72" href="ipad-icon.png" />  
 <link rel="apple-touch-icon" sizes="114x114" href="iphone4-icon.png" />  
 <link rel="apple-touch-icon" sizes="144x144" href="ipad144-icon.png" />  

Now, when a user on an iOS device creates a shortcut to this web application or a specific page, they will get a nice looking, branded icon that represents the application well and gives the user a native feel for launching their application.