Part 1: Initial scaffolding the application

Note: I’m aware of the problems showing < and > in the code sections – Will get them corrected as soon as possible!

To get an overview of the article series read this post.

This post is the first in the series:

  1. Initial scaffolding the application
  2. Layering out the application using dependency Injection
  3. Adding Cross Cutting Concern functionality
  4. Implementing database functionality using an ORM
  5. Integration test using OWIN
  6. Adding more functionality to the application
  7. DevOps, using Continues Integration, deployment and instrumentation.
  8. Security –authorization, authentication and more.

Preparation

In this blog posting we will lay out the initial WebAPI Application. The application itself is a simple music application exposing some simple REST based endpoints related to albums. We will end up with an architecture, that forms the base, or scaffolding,  for the rest of future blog postings.

I presume that you now your basic C#, as well as you have basic knowledges about the articifacts around the .NET stack.

The only thing you need for this posting is any version of Visual Studio 2015.

The basic

Create a new ASP.NET Web Application, and name it JazzAppSample (or whatever you prefer). Make sure that “Application Insights is unchecked. Click “Ok”.

Select the “Empty” ASP.NET 4.5.2 template, and click “OK” (We will add a unit test project later)

You inital scafolding should look like this:

Empty website

Okay, with that in place, next step is to add a controller:

Rightclick the JazzAppSample project, and choose “New Scaffolded Item…”

Add scaffolded Item...

Choose the “Web API 2 Controller – Empty”:

3. Web API2 Controller Empty

Name the controller “AlbumController” and hit “OK”. Visual Studio adds some files and folders.

Open the newly created AlbumController found in the Controllers folder.

As you can see the file only consists of an empty class, the AlbumController class, that inherits from the abstract class ApiController. So we need to add some methods in here to be able to expose anything.

Lets add a default Get method to the class:

Hit F5 to fire up IIS express and navigate to http://localhost:xxxx/api/album where xxx is the portnumber.

The browser should reponse with:

4 Get response

Okay, to make a short recap, What we did so far was to create a basic ASP.NET Web API with a single controller containing a single default GET method that returns a simple text. We tested the method by calling it directly from the browser. That’s all fine, but we will add a hole bunch of methods and (probably) controllers later on, So I think it will be a good time to talk a bit about some of the tool that could be found useful when developing REST based API.

REST Test and documentation tools

If you, like me, use the Chrome browser, I will definitely recommend DHC made by Restlet. If your REST API can be reach from outside (not recommendable) you can go to https://dhc.restlet.com/# and start out there. A much better solution is to install the DHC Chrome app available from the Chrome App Store. The app is pretty much self explanatory so I would not go into detail here. Another tool that you might find useful is  PostMan also a Chrome App, and also a straight forward test tool.

Enter Swagger

For documentation (and test) I use Swagger. The Swagger Specification (Now called OpenAPI Specification), is a ” a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services“.

So how do use this in conjuction with our WebAPI application? It’s pretty easy. The SwashBuckle project found on Github made a NuGet package we can install, and all the magic happens behind. So let’s do that:

Open The Package Manager Console and write:

at the command prompt and hit Enter:

5 install SwashBuckle

After Swagger is installed, try again and F5 start your app and go to http://localhost:xxxxx/swagger. You will be redirected to http://localhost:xxxxx/swagger/ui/index from where you can explorer and try out your API. Cool! Close the debug session again.

Code annotation

In order to get Swagger to consume your annotated code documentation you need to do some simple things.

First of all, rightclick the JazzAppSample project and select “Properties”. Go to the “Build” section and tick the “XML documentation file” checkbox:

6 XML Documentation File

Then open the newly created SwaggerConfig.cs file located in the App_Start folder, and insert the line

just below the line that says

Then open the AlbumController.cs file and add the following comments to the Get method:

That’s it! Swagger will now document your class like this:

7 Swagger code documentation

Return types

If you look at the Response Class in Swagger it just says “OK” (Status 200). If you would like to have you return type documented (and you will believe me!), you have to annotate your method.

So here is what you need to do:

Add the following directive to the AlbumController:

Annotate the Get method with

F5-start the app again and navigate to Swagger and unfold the Album endpoint:

8 responseType

In our case the method just returns a simple type – a string, but later on we will return  domain specific objects, and it would be nice to have them well documented.

Okay, a bit of a detour, so to do a midway recap, what we have in place now is:

  1. The scaffolding of the Web API
  2. A single Controller
  3. A REST Testbench
  4. Some sort of documentation of the REST API

Implementing a Model

Our Get method that we implemented  in the previously section should of course return an object that represents a single album. So we need a place where we can do that. There are several ways of doing that. You can create a folder in your JazzSample Project and add your model classes in there, or you can create a separate project that contains all your models (think reuse:)). So we will go for that:

  1. Add a new Project to the solution (Class Library). Name it: JazzAppSample.Common.Model
  2. Delete the default Class1.cs file
  3. Then add a new class, and called it Album
  4. Create some properties:
  5. Your solution should look like this:9 Adding Model project
  6. Back in the JazzAppSample project, create a project reference to the Model project
  7. Change the Get metod to return an instance of an album:
  8. Run the sample, go to the swagger page and try out the REST call:10
  9. Click on “Model”:11
  10. To get the documentation for our album model: Go to the properties of the Common.Model project->Build->Tick the XML documentation
    Add:

    to the SwaggerConfig file. This will document our Album domain object:
    12

Last thing to do before we go deeper into the scaffolding of the WebAPI, is to refactor our GET method to take an ID an return the specific Album with that Id. So refactor the Get method like this:

Try it out via Swagger:

13

 

Final recap

We reach the end of this posting. In the next part of the series, we will go deeper and add some layers to the architecture. We will look at how we can use a Dependency Injection framework to separate functionality in order to write some tests.

 

WebAPI2, Integration tests, Continuous integration and deployment. An End-to-end sample.

The upcoming blog posasp-dot-net-logotings will catch up with many of the aspect I have been dealing within the last couple of years when developing robust and secure WebAPI2 backend applications

The postings will come in several parts (the order may change):

  1. Initial scaffolding the application
  2. Layering out the application using dependency Injection
  3. Adding Cross Cutting Concern functionality
  4. Implementing database functionality using an ORM
  5. Integration test using OWIN
  6. Adding more functionality to the application
  7. DevOps, using Continues Integration, deployment and instrumentation.
  8. Security –authorization, authentication and more.

 

We will develop a simple REST based application totally from scratch and, as we move along, add more functionality to the application. The goal at the end, is to have a full functionally backend application that can be used with an HTML5 application, a native mobile app or any other kind of application that could integrate to a REST based API.

Furthermore, we will look at various design patterns as well as tools I found useful when developing, testing and deploying WebAPI2 applications.

As there can be different ways of implementing stuff, you might not agree in every (or any) aspect the way I do things, so feel free to drop me a comment with your suggestions or any questions you might have.

Disclaimer: The sample code described herein is provided on an “as is” basis, without warranty of any kind.