DPS907 notes – Thu Sep 8

Our first session in a computer-lab room. Lots of hands-on activity today.

 

Typical agenda for our Thursday classes

On your timetable, this Web Services course is a four-hour course. The Thursday session, in a computer-lab room, is part of the course. It is not optional, and you cannot skip it. The bottom line is that you’re paying for a four-hour course, and that’s what you’ll get from me. I also expect that from you.

During our Thursday classes, we will typically have a mix of discussion/lecture, and hands-on activity. The hands-on activity may help you learn the application of a concept or technique, and will also typically include some time where you get started on the weekly assignment. Often, there will be a brief “work report” that you will submit before you leave the room; it will be graded, and become part of your assignment grade.

Also, the Thursday classes give you an ideal opportunity to get help from your professor. I can help then, or during my “student help time” in my office. I am not available at 3:00am to help you by email/online, so take advantage of the scheduled class times and my office hours.

 

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 green “Clone or download” 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_01”, “Week_02”).

During the course’s lifetime, about twenty or more 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 space- and 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.

Therefore, after you load a code example in Visual Studio, immediately build the project. Either Ctrl+F5 to run without debugging, or “Build Solution” on the Build menu. Visual Studio will re-build the packages folder, and make the project ready for use.

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. 

 

Controller class for a web service

In Visual Studio, when you add a new controller to the Controllers folder, choose this template in the “Add Scaffold” dialog:

Web API 2 Controller with read/write actions

add-web-service-controller

 

The controller source code will be generated, with method stubs for the typical actions:

  • Get all
  • Get one by identifier
  • Add new
  • Change existing
  • Delete item

We will edit the method signatures, and the code in the methods, to meet our needs.

Notice that the controller class inherits from ApiController. This base class is similar in many ways to the Controller base class that you have in ASP.NET MVC web apps.

However, it was created by a different team, and is tuned to the needs of web services. While we can coax the web apps Controller class into use as a web service, it is missing some qualities that we want in our web services.

 

Return type of a controller method

As you begin this Web Services course, you must learn about method return types.

In the previous class, you learned about the request-processing pipeline. In the class notes, in the second-last row of the table, you saw that the data result of an executed method is passed to a media type formatter component – included in the Web API framework – which renders, or serializes, the data result to JSON or XML.

Whether your method return type is an object, or a collection of objects, the serializer does its job, and the user receives valid data in the response.

In all of your work, until further notice, your methods will use only two return types:

  1. IHttpActionResult
  2. void

The first return type – IHttpActionResult – will be used for all methods that return data. This return type will be used on almost all of your methods.

The second return type – void – will be used for methods that do not return data.

You may notice that the Visual Studio code-generator – which can create method stubs for new controllers – does not always use these two return types. In those situations, you must change the return types to IHttpActionResult or void, or create new methods that replace the code-generated method stubs. Do not assume that the code generator is correct.

Why do we care? When you use IHttpActionResult or void as the return type, then the request-processing pipeline adds the correct HTTP status code to the response.

Note:

In the previous class notes, the importance of the RFC7230 series that describes the HTTP protocol was highlighted. The series is also prominently featured in the Resources area of this web site.

RFC7231 will be the most-used document in this course. It has all the answers you’ll need when writing HTTP services.

The HTTP response status codes are discussed in Section 6 of RFC7231.

 

When an ApiController method returns an IHttpActionResult, we use a specific helper method, depending upon the method logic. Most of the helper methods accept one or more arguments, which is how you actually return an object or collection of objects. For example, assume that the method fetched a specific object named “result”. We would use the Ok() helper method:


return Ok(result);

 

Here is an alphabetically-ordered list of helper methods:

BadRequest (returns an HTTP 400 status code)

Conflict (409)

Created (201)

InternalServerError (500)

Json (200)

NotFound (404)

Ok (200)

Redirect (302)

StatusCode (choose from an enumeration of status codes)

Unauthorized (401)

 

Here is the same list, ordered by HTTP status code:

Ok (200)

Json (200)

Created (201)

(remember – a void method return type will deliver HTTP 204)

Redirect (302)

BadRequest (400)

Unauthorized (401)

NotFound (404)

Conflict (409)

InternalServerError (500)

…and… StatusCode, from which you can choose from an enumeration

 

If you’re interested, the origin of these methods trace back to the System.Web.Http.Results namespace.

 

Fiddler testing patterns

As you begin this Web Services course, use the following testing patterns when using the Fiddler tool:

 

Get all request

  • Method is GET
  • URI is the collection URI
  • Optionally, you can specify an Accept header

.

Get one request

  • Method is GET
  • URI includes a segment that has an identifier
  • Optionally, you can specify an Accept header

.

Add new request

  • Method is POST
  • URI is the collection URI
  • Must add a Content-Type header
  • Include a correctly-defined-and-formatted entity body

Usage tip: Execute a “get one” request, and use the response body as a template for entering a new entity body for the “add new” request. Copy, paste, and edit. It will save you a bit of typing.

 

The following is an example of a correctly-formatted “add new” request. Click to open full-size in its own tab/window.

fiddler-how-to-post

 

Get started on the assignment

Assignment 1 is now available.

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

 

 

 

 

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Advertisements
%d bloggers like this: