Building Web Services with Windows Azure (new): Quickly develop scalable, REST-based applications or services and learn how to manage them using Microsoft Azure

What do you get with eBook?

Instant access to your Digital eBook purchase

Download this book in EPUB and PDF formats

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Building Web Services with Windows Azure (new)

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.

Getting to know HTTP

Since we concluded in the previous section that Web APIs are based on HTTP, it is important to understand some of the fundamental constructs of HTTP before we delve into other details.

THE RFC 26163 specification published in June 1999 defines the Hypertext Transfer Protocol (HTTP) Version 1.1. The specification categorizes HTTP as a generic, stateless, application-level protocol for distributed, collaborative, and hypermedia information systems. The role of HTTP, for years, has been to access and handle especially when serving the Web documents over HTML. However, the specification allows the protocol to be used for building powerful APIs that can provide business and data services at hyperscale.

Note

A recent update to the HTTP 1.1 specification has divided the RFC 2616 specification into multiple RFCs. The list is available at http://evertpot.com/http-11-updated/.

An HTTP request/response

HTTP relies on a client-server exchange and defines a structure and definition for each request and response through a set of protocol parameters, message formats, and protocol method definitions.

A typical HTTP request/response interaction looks as follows:

The client made a request to fetch the contents of a resource located at www.asp.net, specifying to use HTTP Version 1.1 as the protocol. The server accepts the request and determines more information about the request from its headers, such as the type of request, media formatting, and resource identifier. The server then uses the input to process the results appropriately and returns a response. The response is accompanied by the content and a status code to denote completion of the request. The interaction between the client and server might involve intermediaries such as a proxy or gateway for message translation. However, the message request and response structures remain the same.

Note

HTTP is a stateless protocol. Hence, if we attempt to make a request for the resource at the same address n times, the server will receive n unique requests and process them separately each time.

HTTP methods

In the preceding request, the first thing a server needs to determine is the type of request so that it can validate if the resource supports this request and can then serve it. The HTTP protocol provides a set of tokens called methods that indicate the operations performed on the resource.

Further, the protocol also attempts to designate these methods as safe and idempotent; the idea here is to make the request execution more predictable and standardized:

A method is safe if the method execution does not result in an action that modifies the underlying resource; examples of such methods are GET and HEAD. On the other hand, actions such as PUT, POST, and DELETE are considered unsafe since they can modify the underlying resource.
A method is idempotent if the side effects of any number of identical requests is the same as for a single request. For example GET, PUT, and DELETE share this property.

The following table summarizes the standard method definitions supported by HTTP Version 1.1 protocol specification:

Method	Description	Safe	Idempotent
`OPTIONS`	This represents the communication options for the target resource.	Yes	Yes
`GET`	This requests data from a specified resource.	Yes	Yes
`HEAD`	This is the same as `GET`, but transfers only the status and header back to the client instead of the complete response.	Yes	Yes
`POST`	This requests to send data to the server, typically evaluates a create request.	No	No
`PUT`	This requests to replace all current representation of the target resource, typically, generally evaluates an `Update` request.	No	Yes
`PATCH`	This applies a partial update to an object in an incremental way.	Yes	No
`DELETE`	This requests to remove all current representation of the target resource.	No	Yes
`TRACE`	This performs a message loop-back test (echo) along the path to the targeted resource.	Yes	Yes
`CONNECT`	This establishes a tunnel to the server identified by a given URI. This, for example, may allow the client to use the Web server as a proxy.	Yes	Yes

HTTP status codes

HTTP status codes are unique codes that a server returns based on how the request is processed. Status codes play a fundamental role in determining response success and failure especially when dealing with Web APIs. For example, 200 OK means a generic success whereas 500 indicates an internal server error.

Status codes play a pivotal role while developing and debugging the Web API. It is important to understand the meaning of each status code and then define our responses appropriately. A list of all HTTP status codes is available at http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.

Other HTTP goodies

From a Web API perspective, there are some other aspects of HTTP that we should consider.

Header field definitions

Header fields in HTTP allow the client and server to transfer metadata information to understand the request and response better; some key header definitions include:

Field	Description
`Accept`	This specifies certain attributes that are acceptable for a response. These headers can be used to provide specifications to the server on what type of response is expected, for example, `Accept: application/json` would expect a JSON response. Note that as per the HTTP guidelines, this is just a hint and responses may have a different content type, such as a Blob fetch where a satisfactory response will just be the Blob stream as the payload.
`Allow`	The header indicates a list of all valid methods supported by a requested resource (`GET`, `PUT`, `POST`). It is just an indication and the client still may be able to seek a method, not from the `Allow` list. In such cases, the server needs to deny access appropriately.
`Authorization`	This is the authorization header for the request.
`Content-Encoding`	The header acts as a modifier to a content type. It indicates the additional encodings that are applied to the body, for example, Gzip, deflate.
`Cache-Control`	This indicates a cache directive that is followed by all caching mechanisms throughout the request/response chain. The header plays an important role when dealing with server-side cache and CDN.
`Content-Type`	This indicates the media type of the entity-body sent to the server.
`X-HTTP-Method`	The header allows clients or firewalls that don't support HTTP methods such as `PUT` or `DELETE` to allow these methods. The requests tunnel via a `POST` call.

Content negotiation

Content negotiation is a technique to identify the "best available" response for a request when multiple responses may be found on the server. HTTP 1.1 supports two types of negotiations:

Pre-emptive or server-driven negotiation: In this case, the server negotiates with the client (based on the Accept headers) to determine the type of response.
Reactive or client-driven negotiation: The server presents the client with the representations available and lets the client choose based on their purpose and goals.

More information about content negotiation can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html.

What you will learn

Build RESTful services using the ASP.NET Web API and Microsoft Azure

Host and monitor applications in Azure Websites and Azure Mobile Services

Manage Web APIs using Azure API Management

Utilize Azure Service Bus to provide elasticity to your applications as well as publish and subscribe features

Utilize the Microsoft Azure Platform as a Service (PaaS) component in your custom solutions

Get to grips with the basic characteristics of distributed systems

Use Entity Framework as the data model

Leverage your cloudbased storage and discover how to access and manipulate data in the cloud

Explore the NoSQL options available in Microsoft Azure

What do you get with eBook?

Instant access to your Digital eBook purchase

Download this book in EPUB and PDF formats

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Frequently bought together

$48.99

$32.99

Building Web Services with Windows Azure (new)

$48.99

Total $ 130.97

Kerry newton Dec 27, 2015

No idea it was a gift for programming son

Amazon Verified review

Vivi Banks Mar 31, 2016

Excellent read

.NET Dev Sep 02, 2015

I am new to this technology and thought a step by step guide would help. I have not been able to obtain the sample code despite repeated e-mails to the publisher. The instructions as to how to interact with Azure are obscure -- no explanation of why or what you are configuring or how the various different parts play together. The wheels fell off at the end of chapter 2 -- there was no getting past the broken instructions there. Prepare for frustration beyond the norm.

Building Web Services with Windows Azure (new): Quickly develop scalable, REST-based applications or services and learn how to manage them using Microsoft Azure

What do you get with eBook?

Building Web Services with Windows Azure (new)

Introduction

Note

Note

Getting to know HTTP

Note

An HTTP request/response

Note

HTTP methods

HTTP status codes

Other HTTP goodies

Header field definitions

Content negotiation

Page 1 of 7

Description

Who is this book for?

What you will learn

Product Details

What do you get with eBook?

Product Details

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

People who bought this also bought

About the authors

FAQs

Building Web Services with Windows Azure (new): Quickly develop scalable, REST-based applications or services and learn how to manage them using Microsoft Azure

What do you get with eBook?

Contact Details

Billing Address

An HTTP request/response

HTTP methods

HTTP status codes

Other HTTP goodies

Header field definitions

Content negotiation

Description

Who is this book for?

What you will learn

Product Details

What do you get with eBook?

Contact Details

Billing Address

Product Details

Packt Subscriptions

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

People who bought this also bought

About the authors

FAQs