Introduction

Application Programming Interface (API) is not a new buzz word in the programming world. If we take a history tour of all programming languages ever developed, we will notice that any language that allowed software components to communicate and exchange information supports the notion of an API. An API can be as simple as defining a function in the procedural language such as C, or can be as complex as defining a protocol standard; while the structure and complexity of an API may be varied, the intent of an API mostly remains the same. Simply put, an API is a composition of a set of behaviors that perform some specific and deterministic tasks. Clients can then consume this API placing requests on any of the behaviors and expect appropriately formatted responses.

For example, consider the following code snippet that leverages the System.IO.File type in the .NET framework to read from a text file and print its contents in a console window:

static void Main(string[] args)
{
    string text = System.IO.File.ReadAllText(@"C:\MySample.txt");
    System.Console.WriteLine("Contents of MySample.txt = {0}", text);
}

In the preceding example, the System.IO.File type exposes a set of specific behaviors that a client can consume. The client invokes a request by providing the required input and gets back an expected response. The System.IO.File type acts like a third-party system that takes input and provides the desired response. Primarily, it relieves the client from writing the same logic and also relieves the client from worrying about the management of the System.IO.File source code. On the other hand, the developers of System.IO.File can protect their source from manipulations or access; well, not in this case because the .NET Framework source code is available under Microsoft Reference Source License. The bits for the .NET Framework source can be accessed at https://github.com/Microsoft/dotnet.

If we now take the preceding API definition and stitch it with a Web standard-like HTTP, we can say that:

A Web API is a composition of a set of behaviors that perform concrete and deterministic tasks in a stateless and distributed environment.

If this feels like a philosophical statement, we will look at a more technical definition when we delve in the ASP.NET Web API in the coming sections.

Before we get into the details of writing our own Web APIs, let's try consuming one; we will use the Bing Map API for our example:

Bing Maps provide a simple trial version of their Map Web API (http://msdn.microsoft.com/en-us/library/ff701713.aspx) that can be used for scenarios such as getting real-time traffic incident data, location, routes, and elevations. To access the API, we need a key that can be obtained by registering at the Bing Maps Portal (https://www.bingmapsportal.com/). We can then access information such as location details based on geo coordinates, address, and other parameters.

In the following example, we fetch the address location for the Microsoft headquarters in Redmond:

The response should look as follows:

{
    "authenticationResultCode":"ValidCredentials","brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png","copyright":"Copyright © 2015 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.","resourceSets":[{"estimatedTotal":1,"resources":[{"__type":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1","bbox":[47.636677282429325,-122.13698331308882,47.644402717570678,-122.12169668691118],"name":"Microsoft Way, Redmond, WA 98052","point":{"type":"Point","coordinates":[47.64054,-122.12934]},"address":{"addressLine":"Microsoft Way","adminDistrict":"WA","adminDistrict2":"King Co.","countryRegion":"United States","formattedAddress":"Microsoft Way, Redmond, WA 98052","locality":"Redmond","postalCode":"98052"},"confidence":"Medium","entityType":"Address","geocodePoints":[{"type":"Point","coordinates":[47.64054,-122.12934],"calculationMethod":"Interpolation","usageTypes":["Display","Route"]}],"matchCodes":["Good"]}]}],"statusCode":200,"statusDescription":"OK","traceId":"a54a3e7f071b44e498af17b2b1dc596d|CH10020545|02.00.152.3000|CH1SCH050110320, CH1SCH060052346"
}

We notice a few things here:

We talk in greater detail about how this request was processed earlier. However, there are two key technologies that enabled the execution of the preceding request, namely, HTTP and REST. We discuss these in greater details in this section.

To explore more free and premium API(s) you can take a look at http://www.programmableweb.com/. Programmable web is one of the largest directories of HTTP-based APIs and provides a comfortable and convenient way to discover and search APIs for Web and mobile application consumption.