DPS907 notes – Tue Sep 5

Welcome to the web services course! This is our first session together.

 

Typical agenda for our Tuesday classes

On your timetable, this Web Services course is a four-hour course. The Tuesday 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 Tuesday 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 Tuesday 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 late in the evening to help you in person or by email, so take advantage of the scheduled class times and my office hours.

 

What is a web service?

A web service is an application that runs on a web server, and is accessed programmatically.

When we parse this short sentence, and consider the meanings behind the simple words, we reveal some very important concepts:

  • HTTP is the protocol, enabling wide use and scalability
  • Humans don’t use a web service directly – instead, the application they are using creates and sends a request to the web service, and handles the response in a way that’s meaningful to the application
  • A web service’s functionality is discoverable, and typically known as an application programming interface (API)

Web services can be developed on any web-connected technology platform, in any language, and can be used on any kind of device.

 

What’s the difference between a web app, and a web service?

Study this diagram to understand the differences, and then be prepared to explain them to someone else:

 

How do I start learning web services?

We will begin today. You will be introduced to a number of web service topics:

  • The request and response pattern
  • The HTTP protocol
  • Development platform (ASP.NET Web API) and tooling (Visual Studio)
  • Testing and interacting with the web service, using Fiddler, an HTTP inspector

Your professor will guide you through the topics, while you use a computer.

 

Creating a web service

We will use Visual Studio 2017 Enterprise in this course to create web services.

Your professor will introduce the tooling, the “Web API” project type, and the process of creating a web service.

Fiddler will be used to interact with the web service.

 

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 next class notes, you will learn about the request-processing pipeline. For now, you should know that a request is handled by a number of distinct code modules or components, including the controller that you are writing. The result of this computational “pipeline” is that a response is generated and returned to the requestor. The response generator is known as a media type formatter – 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 for your situations and use cases.

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

Note:

Today, the professor noted 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: