DPS907 WSA500 Assignment 4

Hypermedia representations.

Read/skim all of this document before you begin work.


Due date

Monday, November 5, 2018, at 11:00pm ET

Grade value: 10% of your final course grade

If you wish to submit the assignment before the due date and time, you can do that.


Overview and purpose

After learning about REST constraints and hypermedia-driven design, you need some experience in implementing the concepts and techniques. Your work will include 1) manually-generated controls, and 2) code-generated controls (using an enhanced media type formatter).


Specifications overview and work plan

Here’s a brief list of specifications that you must implement:

  • Follows best practices
  • Implements the recommended system design guidance
  • Customized appearance on the landing web page
  • Uses Entity Framework and Code First technology
  • Includes a Fiddler log file that shows complete coverage of tests


  • Fully-implemented documentation components (code comments, XML code comments, annotations, Web API Help Page, entry/root URI)
  • Manually-generated hypermedia representation for the Invoice entity, get all and get one
  • Code-generated hypermedia representation for the Track entity, get some (for a specific album)


Students in DPS907 must complete these additional specifications (use cases):

  • Deliver hypermedia representations from PUT (command) and DELETE requests 


During the class/session, your professor will help you get started and make progress on this assignment.

Every week, in the computer-lab class/session, it is possible that your professor will record a grade when you complete a specific small portion of the assignment. We call this “in-class grading“. The in-class grading will be announced in-class by your professor.


Getting started

Create a new web service, named Assignment4. It must use the “Web service project v1” project template.

Build/compile, and run (without debugging), to ensure that the app’s home > index view loads in a browser. Then, customize the index view (with your name etc.) before continuing.


Add the recently-learned code assets

Recently, you learned about several code assets that add value to a web service. Locate these assets, and add them to your project. Yes, you have permission to add, activate, modify (where necessary), and use these code assets in your assignment work.

  • HandleError.cs – error handling
  • CreateErrorController.cs – to enable you to test HandleError.cs
  • ByteFormatter.cs – handle non-text internet media types
  • HRFormatterICT.cs – from the Week 6 folder – classes that support hypermedia representations

Make sure that you activate or configure each one, as you have recently learned. Build/compile and run, to ensure that it still works without errors.

Now, continue by working on the specifications (use cases).


Fully-implemented documentation components

The goal of this task is to fully implement a range of documentation components (code comments, XML code comments, annotations, Web API Help Page, entry/root URI).

For all components, you will have to iteratively work on them, as you work on the other specifications (use cases). In other words, it is unreasonable to expect that you’ll be able to fully complete this task before writing code for controllers and resource models.

Please note:
Do this work now, before starting work on the other specifications (use cases). Do not leave this section of work until after, because the work done later depends on the this section’s work.


Add and configure a controller to handle requests to the entry point.

Which entity (or entities) should you focus on? In this assignment, we will be working with the Invoice and Track entities. Plan on making (eventually) controllers for Invoice, Track, and Album. That fact suggests that we will need resource model classes for those entities too. In addition, there will be properties from other associated entities that we’ll work with too.

Enable the Web API Help Page. As you have learned, a number of tasks are required.


Manually-generated hypermedia representation for the Invoice entity

In this section, we will support get all and get one, for the Invoice entity. The hypermedia representation will be manually-generated.

Please note:
There are many invoices. Maybe your manager method for get all should take and deliver only some (maybe 10 or 20). That will make it easier to test and configure.


Create a controller to handle Invoice requests. As noted above, it will need methods to handle only the get all and get one requests. Obviously, this task requires resource model classes to be created, and manager methods.

The resource model class for the Invoice entity must include these specific additional properties from associated objects:

  • Number (count) of invoice line items
  • From the associated customer… company name, first name, and last name

The delivery of hypermedia representations (HR) will be done by writing code in the controller, as you learned in the Week 5 code example. The get all HR will include a link to self, and each item in the collection will include the recommended links. The get one HR will include the recommended links to self and to the collection.

As you make progress on this task, use both Fiddler and the Web API Help Page to test your work.


Code-generated hypermedia representation for the Track entity

In this section, we will support get some, for the Track entity. Some? We will actually do this by working with an Album controller and attribute routing. The hypermedia representation will be code-generated, using the enhanced code in the HRFormatterICT class.

Why are we working with the Album controller to do Track-related requests? So that we can support the following URI pattern to support GET and POST:


In the Week 6 “HRFormatterICT” folder of the code repository, there are a number of interesting assets:

The original HRFormatterICT.cs source code file has been renamed to HRFormatterICT-original.cs.

A new and enhanced HRFormatterICT.cs source code file will be used in your solution (below).

A README.md file that tells you about the packaging formats used in the formatter.

An image that shows our goal/objective – image-api-albums-80-tracks.png. It shows one album (AlbumId 80) with its tracks and links/controls.

A file – json-plain-api-albums-80-tracks.txt – that has the data WITHOUT links/controls (plain/bare JSON).

Another file – json-with-links-api-albums-80-tracks.txt – that has the data WITH links/controls.


Get started on a solution

Add an Album controller and resource model classes. Write the code to support the following use cases:

  • get all
  • get one
  • add new
  • edit existing (allow the Title property to be edited)
  • delete item

In these controller methods, do NOT add code to generate hypermedia representations.

Test your work before continuing. Make sure that plain/bare JSON is delivered.

Add (copy) the enhanced HRFormatterICT.cs source code file to your project. This file is in the Week 6 folder of the code repository. It will replace the existing file in your project.

Test your work again. This time, the requests will ask for the application/json+ict media type.


All tracks for an album

As stated earlier, we will actually write the code for this use case in the Album controller. Yes, we could put it in a Track controller, but we will not do that here.

The “get” method must use attribute routing, for this URI pattern:


The argument will be the album identifier. The sample results and image discussed above show the result of delivering data with AlbumId 80.

The manager method will deliver a collection of TrackWithDetail objects. Therefore, you must write some resource models that include data from associated objects, and “include” those in the query. The logic of the manager method will ask for a collection that matches a condition (the AlbumId value).

The TrackWithDetail resource model class can be based on (i.e. inherit from) a TrackBase class. Its additional properties can be either the full objects (Album, Artist, MediaType, Genre) or just the useful and display-friendly properties in those objects. Your choice. (The sample results and image discussed above show the full object result.)

When you deliver the hypermedia representation results the first time, you may notice that your results are not as rich as the sample results discussed above. You can fix this by adding documentation to your controller methods and to your resource model properties. Review the notes and scan the HRFormatterICT.cs source code to remind you of the work to be done.

Tip/suggestion: You might want to write a Track controller, with simple get-all and get-one methods, so that you can easily test your work and give you the confidence that you’re making progress.


Add a new track to an album

As stated earlier, we will actually write the code for this use case in the Album controller. Yes, we could put it in a Track controller, but we will not do that here.

The “post” method must use attribute routing, for this URI pattern:


The argument will be the album identifier.

The request’s entity body will be a TrackAdd object. In its resource model class, ensure that the integer values for AlbumId, MediaTypeId, and GenreId are required. (How do we do that for integers?) Yes, we know that the design model classes do not require those values, but we will make them required here for this project.

The manager method will deliver a TrackWithDetail object. The logic of the manager method will validate and fetch the associated objects, before attempting to create a new Track object. Before saving the new Track object, make sure to configure its associated properties with the fetched (associated) object data.


What you’re looking for

Study (again) the sample results discussed above, and compare them to your results. If you have documented your controller methods and resource model properties correctly, the results will include links for all possible tasks that can be done on a URI.


DPS907 students:
Deliver hypermedia representations from PUT (command) and DELETE requests

We have learned that we typically respond with an HTTP 204 status code from “command pattern” PUT requests and from DELETE requests. The controller methods are coded to return “void”, or nothing. 

As you recently learned in the notes, maybe that is not useful to the requestor. Maybe we should tell them a bit more about the result of their request, and send them some links/controls. In this section, we will do that. 

What should be returned? We suggest that you create a new “message” resource model class (somewhere), with two properties:

  • Id, to hold the identifier of the object being processed
  • Message, to hold a suitable message

Then, in the affected controller methods, change the return type to match the other methods. 

After processing, but before the end of the method code block:

  1. Create an instance of the “message” resource model class 
  2. Configure its properties with appropriate values
  3. Return that object in a standard “ok” wrapper

The result is that the requestor will get feedback on their request, and will know what they can do next. 


Testing your work

Use Fiddler.

Test all scenarios (use cases).

This time, add some requests that you know will cause HTTP response errors (400s and/or 500s), so that we know that your app is responding with the correct status code etc.

Again, remember the tip from the notes:
Create a plain text file in your project root to store entity bodies that can be used in copy/paste.


Saving – “exporting” – your tests

On the left side list of requests, you can delete items that you do not want to be included in the export.

When you’re ready to save, choose File > Export Sessions > All Sessions…

The export format will be “HTTPArchive v1.2”. Click the Next button to choose a save location (your project’s root, in the same folder level as the “packages” and “assign1” folder) and specify a filename. Name the file by using the project name (e.g. “whatever.har”).

(You can test whether the export was successful. How? First, close then re-open Fiddler. Choose File > Import Sessions. Select “HTTPArchive” as the import format. Navigate to the folder that holds the “.har” file, and select it. Finally, browse through the request-response sessions.)


Reminder about academic honesty

You must comply with the College’s academic honesty policy.

Although you may interact and collaborate with others, you must submit your own work.

When you are ready to submit your work, you will copy some of the code in your project to plain text files, so that the My.Seneca/Blackboard “SafeAssign” tool can do its job. The next section will tell you which files to copy.

From the Blackboard web site:
SafeAssign compares submitted assignments against a set of academic papers to identify areas of overlap between the submitted assignment and existing works.


Submitting your work

Here’s how to submit your work, before the due date and time:

1. Locate the folder that holds your solution files. In Solution Explorer, right-click the “Solution” item, and choose “Open Folder in File Explorer”. It has three  (or more) items: a Visual Studio Solution file, a folder that has your project’s source code, and a “packages” folder. Go UP one level.

2. Make a copy of the folder. (You will be uploading a zipped version of the copy.)

3. Add a new folder named “MyCode” to the root of the copied folder.

4. Remove the “packages” folder from the copied folder; also, remove the “bin” and “obj” folders.

5. Copy these source code files from your project to the “MyCode” folder:

  • Manager.cs
  • Invoice_vm.cs
  • InvoicesController.cs
  • Track_vm.cs
  • Album_vm.cs
  • AlbumsController.cs

For each of those files, change the “cs” file name extension to “txt”.

6. Compress/zip the copied folder. The zip file size SHOULD probably be less than 10MB (and definitely less than 50MB). If it isn’t, you haven’t followed the instructions properly.

7. Login to My.Seneca/Blackboard. Open the Web Services course area. Click the “Assignments” link on the left-side navigator. Follow the link for this assignment. Submit/upload your zip file. The page will accept three submissions, so if you upload, then decide to fix something and upload again, you can do so.































%d bloggers like this: