DPS907 notes – Tue Sep 26

Internet media types in web services.

 

Code examples

In the GitHub code example repository for this week, you will see several interesting assets.

The MediaUpload code example will be studied today, and discussed in the notes below.

Soon, another code example, MediaUploadAndDeliver, will be posted, and we’ll discuss that in the Thursday class/session.

The ByteFormatter folder has a fully-working and complete media type formatter, built with the instructions that are in the Thursday notes.

 

Reminder – use the Visual Studio Task List…

Make sure that your Visual Studio app is configured to use the “ATTENTION” comment token.

Then use Visual Studio’s “Task List” to help you study the design and coding features of the code example.

 

Transition your web apps media-handling knowledge

All students have experience with media handling in web apps. In this section, you can begin to transition your knowledge to the web services context.

Refresh your memory about media handling in web apps…

Read and study the professor’s class notes and code examples on this topic, recently covered in a web apps course:
BTI420 Class Notes – March 22, 2017  – working with internet media types, simple
BTI420 Class Notes – March 24, 2017 – continued, more complex scenario

It will take about an hour for you to go through that content, and its code examples. Do it now. Before continuing.

 

Welcome back.

In a web app, you learned how to accept (i.e. “upload”) a media item, and how to deliver a media item. You probably coded these kinds of solutions:

Accept (upload)

  • HTML Form
  • Includes an “input type=file” element
  • The form may also have included other input elements

Deliver

  • Specialized controller, or specialized methods in an existing controller
  • Returns a File() ActionResult object

 

The web service solution

Accept (upload)

Well, a web service obviously does not have an HTML Form. Therefore, accepting a media item must be done as an atomic and specialized task. The requestor must send only the media item, and its media type (as a content type header), in the request.

If the media item is to be “linked” to an entity object, then that object must exist, before adding/uploading the media item.

In other words, if you are coding a solution that enables a requestor to, for example, create a new “product” object that has a photo as one of its properties, the solution requires the requestor to create two separate requests. First, create the “product” object by supplying data that can be expressed in the “application/json” media type. Then, using the new object’s identifier, create another request to modify the object, and send along the media item as an “image/png” media type.

Deliver

This part of the solution will be similar to the web app solution. The only difference is that the method return type will be different, because it can take advantage of some functionality that you can build into the web service.

 

Media handling scenarios

There are at least three scenarios for handling media:

Object with one media item
An entity that can also be represented with a media item.
For example, a Seneca “student” object has a single photo item.
Or, a “song” object has a single audio (e.g. m4a, mp3) item.

Today’s code example covers this object-with-one-media-item scenario: MediaUpload.

Object with many media items
An entity that may have zero or more associated media items.
This scenario requires a separate “media” entity, associated to its parent entity.
For example, a “product” object has a collection of product photo items.

Media driven app
In this scenario, the media drives the app’s purpose and design.
The “media” entity is central to the design model, and will be associated (by definition, or logically) with other entities.
For example, a photo app, like Instagram.
Or, a video app, like YouTube.
Or, a music app, like Apple Music.
Or, a document (file) app, like DropBox.

 

Rules

There are at least two important rules that you must follow when working with media items:

Rule:
In a request or response, do NOT package a media item inside another container.

Never.

Accept or deliver the media item as-is, even if it means that the requestor must create another request to fetch the item.

Rule:
When storing a media item, its media type name MUST also be stored.
Therefore, two properties are required, in a design model class, to store a media item:
1. A byte array (in C# + Entity Framework + SQL Server), maybe named “Content” or “Media”, and
2. A string for the type name, maybe named “ContentType”
Yes, you can add other metadata properties (e.g. location, caption, tags, etc.) for the media item, if you wish.

 

Message lifecycle (aka “request-processing pipeline”)

Before continuing, let’s look at a topic that has been briefly and gently introduced a couple of times already.

You are probably aware that a request message flows through a request-processing pipeline before a response is returned to the requestor.

It’s time to learn more about the message lifecycle, so that you can modify or affect a message as it flows through the pipeline. In a few weeks, you will learn how to handle exceptions, and the HTTP OPTIONS method. Both tasks require you to create code that “plugs in” to the pipeline. The pipeline can be modified, customized, and extended.

The image below shows the message lifecycle. Click to open a PDF full-size in its own tab/window.

aspnet-web-api-poster

 

Flow from the request to the controller action

The following is a brief summary of the flow:

  1. Web server host handles the request, and creates an HttpRequestMessage object
  2. Routing dispatcher module activated for a Web API (or MVC) request
  3. Controller dispatcher selects controller, then the action (method)
  4. If applicable, authentication happens
  5. If applicable, authorization happens
  6. Model binding happens, for data in the URI, headers, and entity body *
  7. Controller action (method) is invoked, with the data

* The deserialize task is done by a media formatter.

 

Flow from the controller action to the response

The following is a brief summary of the flow:

  1. The result of the controller action (method) is converted to an HttpResponseMessage *
  2. If the result was an error, the built-in error handler is invoked
  3. Web server returns the HTTP response to the requestor

* For a successful result, the serialize task is done by a media formatter.

 

Summary

We wanted to leave you with this understanding, because it starts to become very relevant when handling internet media types in a web service.

 

Get started on the assignment

Assignment 4 is now available.

Before leaving the classroom at the end of the timeslot, hand in your work report.

 

 

 

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Advertisements
%d bloggers like this: