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.

Note

Note that the semantics of a Web API do not necessarily require it to leverage HTTP as a protocol. However, since HTTP is the most widely used protocol for Web communication and unless some brilliant mind is working on a garage project to come up with an alternative, it is safe to assume that Web APIs are based on HTTP standards. In fact, Web APIs are also referred as HTTP Services.

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"
}

Note

To run the preceding example, we use a Chrome browser extension called Postman (https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en). It provides a good GUI interface to allow executing HTTP Services from within the browser without writing any code. We will use Postman for examples in this book. However, other tools such as Fiddler (http://www.telerik.com/fiddler) can also be used.

We notice a few things here:

• We did not write a single line of code; in fact, we did not even open an IDE to make to call to the Web API. Yes, it is that easy!
• The Bing API presented the caller with a mechanism to uniquely access a resource through a URI and parameters. The client requested the resource and the API processed the request to produce a well-defined response.
• The example is simple but it is still accessed in a secure manner, the Bing API mandates that an API key be passed with the request and throws an unauthorized failure code if the key cannot validate the authenticity of the caller.

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.