DPS907 notes – Tue Sep 6

Welcome to the web services course! This is our first session together.

 

What is a web service?

A web service is an application that runs on a web server, and is accessed programmatically.

This simple sentence contains a number of very important concepts and techniques, including:

  • HTTP is the protocol
  • A web service is defined by its application programming interface (API)
  • Humans don’t use a web service directly – instead, the application they are using creates and sends a request to the web service, and handles the response in a way that’s meaningful to the application they’re using

 

What’s the difference between a web app, and a web service?

These diagrams should help illustrate the difference.

web-app-vs-web-svc

 

Give me a brief history lesson on web services

With the rise of the web’s use and popularity in the 1990s, efforts were made to define and specify web services.

This led to the de facto standardization of SOAP XML web services. Often described as “big web services”, SOAP XML web services are the implementation of remote procedure calls on the web. This kind of web service typically has one specific endpoint address, and requestors must create and send a data package (which conforms to a data format named SOAP), and then process the response (which also conforms to SOAP).

However, other efforts took advantage of the web and its existing features and benefits. In other words, they simply followed the HTTP specification and its ex post facto architecture definition, to create true and pure web services. These kinds of web services, often termed “Web API”, or “HTTP services”, exploded in use and popularity from about 2005 onwards, and are now the preferred design approach.

In this course, you will learn both (for maximum employment value). However, most of our work will use the modern web services.

Web services can be developed on any web-connected technology platform, and in any language. Web services are interoperable.

 

Are web services important?

Yes.

Absolutely.

Web services are vital for modern software architectures.

For all device platforms.

 

How do I start learning web services?

You must learn (more) about HTTP.

In class, we will discuss some HTTP topics, and refer to the overview on Wikipedia, and the official specification series, RFC 7230 to RFC 7235, which replaced RFC 2616 in June 2014.

 

Request, response 

HTTP is a typical Internet protocol that relies on an exchange of messages between a requestor and a responder. The messages are plain text, and must conform to a specific format.

An example of a request message is shown below. The resource at “/index.html” is being requested:

GET /index.html HTTP/1.1
Host: www.google.ca

 

An example of the response message is shown below. Some data has been removed to simplify the example. Notice the empty line in between the headers and the message body:

HTTP/1.1 200 OK
Date: Sun, 06 Sep 2015 16:29:52 GMT
Content-Type: text/html; charset=ISO-8859-1

<!doctype html>
<html itemscope="" itemtype="http://schema.org/WebPage">
<head>
<meta itemprop="image" content="/images/google_favicon_128.png">
<title>Google</title>
<script>
(function(){

 

HTTP requests used in this course

HTTP supports a number of request methods. We will use (at least) the following in this course:

  • GET – read/fetch a resource
  • POST – add to a resource (the resource is typically a collection)
  • PUT – modify an existing resource
  • DELETE – delete an existing resource
  • OPTIONS – ask for a list of request methods that are supported by a resource
  • HEAD – ask for the response headers for a resource

 

Get started with Fiddler

Fiddler is an HTTP inspector.

We will use Fiddler to interact with a web service.

It is installed on the College lab-room computers, and is also available from the Fiddler web site.

 

Important features

There are three important features in Fiddler, for beginners:

  1. Composer – enables you to compose and send an HTTP request
  2. List of requests – saves all of the requests from the current session
  3. Inspector – enables you to inspect the contents of the request and its response

The following shows the Fiddler feature layout. (Click to open it full-size in its own tab/window.)

When Fiddler loads, ensure that it is not “capturing” traffic from other open browser windows on your computer. Look in the lower-left corner; if it says “Capturing”, then press F12 to stop capturing.

Can you save this setting? Yes. Open Tools > Fiddler Options. On the Connections tab, un-check (clear) the checkbox named “Act as system proxy on startup”.

 

fiddler-intro

 

How to compose and send a request

Carefully select and edit the following:

  1. Request method – choose GET, POST, PUT, DELETE, OPTIONS, etc.
  2. URI – enter the URI of the resource
  3. Request headers – if needed, you must add request headers (e.g. Accept, Content-Type, Authorization etc.)
  4. Request body – if needed (e.g. in POST and PUT requests), add data that matches the Content-Type specified in the request header; use the “Upload file…” link if you have byte-oriented content to add (e.g. an image, etc.)

After the request has been composed, Execute to send the request. The result will appear in the left-side list of requests. Be patient, because some requests can take several seconds to complete.

fiddler-how-to

 

Interact with the Apple iTunes Store “search” web service 

Use Fiddler to call the Apple iTunes Store “search” web service, which delivers a JSON document. An example URI, for all items from Yo-Yo Ma that include the word “oboe“, is:

https://itunes.apple.com/search?media=music&term=yo-yo+ma+oboe

 

Creating a web service

We will use Visual Studio 2015 (Enterprise, with Update 3 or later) in this course to create web services.

Your professor will introduce the tooling, the “Web API” project type, and the process of creating a web service.

Fiddler will be used to interact with the web service.

 

OK… what’s a resource?

A resource is a digital asset.

Familiar examples include a document, or an image.

How do you identify a resource? By using its URI (uniform resource identifier). The URI standard is described in RFC 3986, and also in a Wikipedia article.

What is the format, or representation, of the resource? Well, it depends on the design of the web service, and sometimes the needs of the requestor.

 

OK… what’s a representation?

As defined above, a resource is a digital asset.

A representation is a digital asset that is formatted as a specific internet media type.

Think about a scenario where a web service was used to manage students in a course. Each student is a resource – a digital asset – that can be identified by a URI.

If a user requested a specific resource through a web browser, you would expect that the resource would be represented by some HTML that included the student’s name, student ID, and so on.

Alternatively, it’s also possible to request the same specific resource – using the same URI – but also specify that it be returned in a data format (like JSON or XML, discussed later). The server will return a data representation of the resource.

Or, maybe the request specified that the student’s photo be returned as the resource’s representation. Again, the same URI is used.

So, in summary, a resource’s representation can vary to meet the needs of the web service programmer or the web service user. The requestor and responder use a feature called content negotiation to make this happen.

Every representation is defined by an internet media type.

representations

 

Get started with internet media types

Your professor strongly recommends that you review the notes about media types on the web apps course web site. Do that now.

Welcome back.

An internet media type is defined as a data format for a representation of a resource on the internet.

The data formats are standardized, published, and well-known, by the IANA (the Internet Assigned Numbers Authority).

This Wikipedia article is an acceptable introduction to internet media types.

For web service programmers, two important internet media types are used as data formats, JSON and XML.

Both are plain-text data formats. They are somewhat human-readable.

Later, you will learn how to work with non-text media types. Now, we will work with plain-text JSON.

 

Get started with JSON

JSON is an initialism for JavaScript Object Notation.

It is a lightweight data-interchange format. It is language-independent, however it uses conventions that were first suggested by the JavaScript object literal or initializer. Many other languages (including C#) now use a similar approach when creating objects. JSON has become a good and comfortable way to describe data for interchange purposes.

Here’s an overview of JSON from Wikipedia.

Here’s the official web site for JSON, by Douglas Crockford.

Although JSON is historically derived from JavaScript object literals, there are a few notable differences to programmers who are new to JSON:

In JSON, each property name is surrounded by double-quotes. That’s not the situation in JavaScript.

In JSON, there is no Date type. Dates are expressed as strings, almost always in ISO 8601 format. In contrast, JavaScript does have a Date type.

 

Get started with XML

XML is an initialism for eXtensible Markup Language.

Students in this course will recognize XML and recall their past experience with applications of XML, specifically HTML, and the Web.config settings in ASP.NET.

In general, XML uses programmer-defined element names to define the data. There are several popular XML document formats that have been created over the years, which can ease the burden of designing a “schema“.

When working with XML, these are the most important rules:

  1. Must be well-formed
  2. Must be based on a schema

Well-formed rules:

  • The (optional) first line is the XML declaration: <?xml version=”1.0″ encoding=”UTF-8″ ?>
  • The second line is a single ‘root’ element to contain all other elements; the root element will likely include a reference to a schema
  • Elements must have a start tag and an end tag, and are case-sensitive
  • Elements must be properly nested, and cannot overlap

Schema rules:

  • The XML documents we use in this course typically use the XML Schema standard
  • However, we may encounter examples that use the RSS or Atom formats

Here’s an overview of XML from Wikipedia.

 

Brief demonstrations – create and test a web service

Your professor will use Visual Studio 2015 to create a simple web service.

Then, Fiddler will be used to test (and interact) with the web service.

 

Introducing ASP.NET Web API

Microsoft describes “ASP.NET Web API [as] a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework.”

The framework includes classes, ready-to-use components, and a server runtime. Overall, the framework makes you very productive.

Web API has a well-defined processing model – known as the request-handling pipeline – for handling requests and generating responses. The pipeline is also configurable, and extensible.

 

Web API projects in Visual Studio

Every student is familiar with the way to create an ASP.NET MVC web app project in Visual Studio 2015.

Creating a Web API project is done in a similar manner. Select the “Web API” project type in the dialog. For best results, in the first few projects you create, configure the project with no authentication.

In the Controllers folder, notice the Values controller. It inherits from a type ApiController.

Please notice that the Web API project also includes the web app components. Notice the Home controller. Therefore, a Web API project can also have user-visible and user-browsable web pages. Very convenient.

 

Interacting with your project

Similar to web app projects, you can load and run your Web API project on your computer’s on-demand web server. Without debugging, the keyboard shortcut is Ctrl+F5, just like you did with web app projects.

A browser will open, and show the project’s home page, which is a web page (home controller, index view).

Copy the URL, and then use it as the base URL when you are using Fiddler. Add /api/values to the URL to fetch content.

 

The request-processing pipeline

In your ASP.NET MVC web apps programming course, you learned that a request goes through a processing “pipeline”, as the response is being prepared. You will learn much more about the pipeline in this course, but you should know at least the following facts now.

Compare the pipelines for requests to a web page resource and to a web service resource:

Web app Web service
Incoming request Route inspection and matching Same
Locate and initialize the controller Same
Perform authorization, by inspecting the incoming identity package (a cookie) Similar, but the identity package is a token
Pass incoming data to the method, do model binding Same
Execute method, which typically passes data (object or collection) to a view engine, which uses a view object to render HTML Similar, but the data is passed to a built-in media type formatter, which renders JSON or XML
Outgoing response Delivered to the requestor Same

 

Do you notice the differences?

  • The passed-in identity package is in a different format
  • The method execution result is handled by different modules in the pipeline

 

 

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

%d bloggers like this: