DPS907 notes – Tue Oct 10

Designing a media formatter for a hypermedia representation.

 

Getting started on our solution

This week, we will design a solution that will automatically generate a hypermedia representation (hr).

Last week, and in Assignment 5, you learned how to manually generate an hr. You saw that the work was tedious, and it bloated the size of the code in the controller, which is something that we really do not want to do. There must be a better way.

In the past, you have learned something about the message-handling (or request-handling) pipeline. In ASP.NET web apps and services, the pipeline is configurable, with a number of locations that can accommodate plug-in custom code. We did this with the error handler, the OPTIONS method handler, and the media formatter for byte-oriented content.

For our solution, we will attempt to design a media formatter that will do the task. Why a media formatter? Well, it is a convenient way to deliver a response that’s customized. It’s easy to configure, and easy to use.

The implication of using a media formatter is that the requestor must include an “accept” header in the request, with a value that matches the a custom and unique name for the internet media type that we will design.

 

Solution roadmap

This week, there are several tasks that we must do to write the media formatter.

First, we must study the typical use cases, and identify the use cases and their typical request-response formats.

Then, we will anticipate the link relations that each use case will need.

 

Request and response metadata (and data)

We will work through some scenarios in class. Then, right after, we may publish notes and code example(s).

Let’s identify the range of use cases. Then, we will look at each request and its response. We have a couple of goals:

  1. Identify the metadata that is typically present in the request
  2. Anticipate the links and actions that will be needed in the response

When we have done that, we will have a “recipe” for coding the media formatter.

The use cases:

  1. Get all
  2. Get some filtered
  3. Get one by id
  4. Get one, by some other value
  5. Get, using attribute-defined route
  6. Add new
  7. Edit existing (seldom done, instead, do a command)
  8. Delete item (seldom done)
  9. Command

Let’s deal with the easy ones first…

 

Delete item

Return type is void, which yields HTTP 204, no message body, and therefore no hr is needed.

 

Command

Return type is void, which yields HTTP 204, no message body, and therefore no hr is needed.

 

Others…

Now, we can look at the others. What links must be created? How “deep” should we go? For our “version 1”:

  • In the item in the “data” property, there will usually (almost always? always?) have only one link
  • If the item (in the “data” property) includes associated data, that associated data does NOT get links

Methods… should we assume GET unless otherwise told? Yes, probably. Or explicitly send that all the time?

Same thing with (internet media) type? Assume JSON (or a custom variant)? Yes.

 

Get all

Pattern 1 – what data and metadata is available?:

  • 1 URI segment (after /api/)
  • 0+ items

 

Get some filtered

Pattern 2:

  • 1 URI segment
  • 0+ items
  • Request.GetQueryNameValuePairs() is not null

 

Get one by id

Pattern 3:

  • 2 URI segments
  • 1 item
  • has id value (greater than zero)

 

Get one, by some other value

Pattern 4:

  • 2 URI segments
  • 1 item
  • does NOT have id value (it will have some other value)

 

Get, using attribute-defined route

Pattern 5:

  • 3+ URI segments
  • 1 item
  • has id value

 

Add new

Use pattern 3.

 

Edit existing (seldom done, instead, do a command)

Use pattern 3.

 

Links and actions (link relations) needed

Based on the work above, we will use a spreadsheet/workbook to begin designing the link relations for each use case.

We will rely on a modified version of the “link” and “MediaTypeExample” classes that we introduced last week.

(professor-led discussion)

 

Assignment info

By design – check the weekly schedule – we do not have a new assignment release today.

Use the extra time this week to ensure that you’re on top of the work in your other courses.

The next assignment will be published next Tuesday, and it will be due at the end of study week.

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Advertisements
%d bloggers like this: