DPS907 notes – Tue Sep 9

Prepare to use Azure. Then, a comprehensive ‘get started’ introduction to web services.

.

Code examples for this semester

Code examples will be published on a public GitHub repository.

GitHub is a hosting service for source code. It offers a web interface to enable easy browsing. It also offers a set of tools and capabilities that enable software developers to publish code, collaborate with others, and improve their productivity and effectiveness.

On this web site, a link to the repository is on the right side of the page, near the top. (For best results, open the link in a new tab or window.)

Beginners can use a web browser to view the source code. You can also click the “Download ZIP” button to get a full and complete copy of all code examples in the repository.

For this course, the code examples will be published weekly, in logically-named folders (e.g. “Week_02”).

During the course’s lifetime, about twenty code examples will be published.

As you have observed, each ASP.NET web app or web service project includes a sizable “packages” folder. In the GitHub code repository, each distinct code example does not include the “packages” folder, as a time-saving measure. Each “packages” folder is about 50MB in size, so twenty code examples would require about 1GB storage. The contents of the “packages” folder does not compress much.

However, a single “packages” folder has been placed at the root of the repository. After you download-and-unzip the repository, simply copy-paste the “packages” folder into any distinct code example’s folder to make it ready for use and learning.

All code examples are designed to be usable and error-free. Each should compile and execute correctly. 

If you have any problems with a code example, please contact your professor. 

.

Prepare to use Microsoft Azure

You will be using Microsoft Azure services to host your web services.

Each student will receive a Student Pass, which provides a range of free (no cost) services for five months.

To redeem your Student Pass, you will need a Microsoft Account.

Here’s what you can do to prepare to use Microsoft Azure.

.

Confirm that you have a Microsoft Account

You may already have a Microsoft Account. Visit this link to learn more.

If you already have a Microsoft Account, then login, using the “Sign in” link in the upper-right area of that page.

If you need a Microsoft account, then follow the link to the “sign up page“; you’ll find that near the bottom of that page.

.

Redeem your Student Pass

Your professor will give you a sheet with a Student Pass “promo code”.

Visit microsoftazurepass.com. Select “Canada”, enter your “promo code”, and submit to begin the redemption process.

RedeemPass

.

Wait for an email from Microsoft

After a few hours (or a day or so), Microsoft will send you an email with information about your Microsoft Azure “Student Pass” subscription.

If possible, please do this today, so that you will be able to use Azure services in the next class on Thursday.

.

Brief review

We’ll do a brief review of the ideas we introduced in last Thursday’s first session.

  • What is a web service?
  • How do I start learning web services?
  • Get started with Fiddler

.

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

.

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.

Every representation is defined by an internet media type.

representations

.

Get started with internet media types

An internet media type is simply 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.

.

Get started with JSON

JSON is an initialism for JavaScript Object Notation.

Its name says it all: This data format is the JavaScript object literal format.

Here’s an overview of JSON from Wikipedia.

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

.

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 XHTML, 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.

.

The MVC design pattern

Modern web apps and web services are often based on the MVC design pattern.

MVC – model – view – controller – enables the programmer to clearly separate code modules into different roles:

  • Model code describes the app’s data, also known as persistent state
  • View code presents the app’s data to the user or requestor
  • Controller code interacts with the user and therefore manages the app’s workflow

The important idea is that the controller is the most important role. User input is handled by the controller, which then works with the app’s data, and then prepares the view that’s returned to the user.

How does this map to a web service?

  • Model code does the same job as it does in a web app
  • View code is not present; the response is prepared by the default built-in serializers, or in code that you write
  • Controller code handles HTTP requests, and implements the web service’s application logic

Read an overview of MVC in this Wikipedia article.

.

Inside a Web API project

An ASP.NET MVC web app or web service uses the front controller pattern (Wikipedia overview article). Every request is inspected by a single controller, and then dispatched to the code module that can handle the request.

The dispatch destination is defined by routes. By default, web service request URIs include an “/api/” segment, although we can change that default in the future. Then, by default, the next segment of the route designates the controller that will handle the request. The HTTP request method, along with the presence of a query string, and/or an entity body, will then determine the method in the controller that handles the request. Routing basics are covered in this ASP.NET Web API article.

Data in-and-out of  the web service is handled by serializers. By default, the Web API project template can handle three internet media types:

  • XML
  • JSON
  • Multipart form data (i.e. data from HTML Forms)

Serialization is introduced in this ASP.NET Web API article.

.

System design guidance and how-to

During this course, you will learn to create a web service that has some level of sophistication. Therefore, you will need some guidance on how to design the system.

In your second-year web app programming and systems analysis courses, you used a “system design guidance” diagram to help you learn a set of topics. We will use a version of that diagram that’s customized for a web service.

Early in the course, you will use a ‘simplified’ diagram, but soon after, you’ll use the ‘complete’ version.

Simplified (click to open a PDF in a new tab/window):

guidance-simplified

 

.

Complete version (click to open a PDF in a new tab/window):

guidance-complete

.

Preview of today’s examples

  1. We will create three project examples today:
  2. Simple web service that uses data that’s created in the controller
  3. Web service that uses a persistent store and the familiar architecture of an ASP.NET MVC web app
  4. Web service that supports a range of HTTP methods

.

Web service project assembly

In this section, you will learn to assemble a web service project. You will take advantage of your ASP.NET MVC web app knowledge and experience.

Remember, we are using Visual Studio 2013, with Update 2 or later (check HELP > About Microsoft Visual Studio for details).

Create a new project. In the “New Project” dialog, select the “ASP.NET Web Application” project template. It’s the only one that’s offered on the Installed > Templates > Visual C# > Web node.

Select a storage location, and name your project. Un-check (clear) “Add to source control”. Click OK to continue.

On the next dialog, “New ASP.NET Project”, select the “Web API” template. Un-check (clear) “Add unit tests”.

Authentication should be set for “No Authentication”. In the Azure section, un-check (clear) “Host in the cloud”. Click OK to continue.

So far, not much different from what you did when creating a web app.

.

Configure non-persistent data and test the controller

In the ValuesController.cs source code file, add a property that will hold some data that you use to test the controller.

.

Add the data persistence package

Add Entity Framework to your project, using the NuGet Package Manager.

 

.

.

.

.

.

.

.

.

.

.

.

.

.

Advertisements
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: