Web API: Resource Model isn’t your Data Model

Web API: Resource Model isn't your Data ModelI was recently reminded of some troubles I had awhile ago which were caused by exposing my data model. This tweet by Mike Amundsen brought up some thoughts that I had yet to share, and why I now suggest that you don’t expose your data model.

OData

A good illustration of the above is with how you see most examples of using OData with .NET and Entity Framework.

The problem lies that the model being exposed via Web API/OData is your backing Entity Framework data model.

In this case, your Data Model (Table) is your Object Model (C#) is your Resource Model (OData).

The Problem

There are a couple issues with exposing your data model.

The first one is pretty apparent the moment you need to start changing your data model.

Having the consumers of your API being loosely coupled poses some challenges when you change the backing model.

If you are creating a public API, you have no control over the clients.  And if the app is internal and you do control the clients, it can still be a nightmare updating them to work with your new data model.

Versioning

You could make the argument that you need to version if you are going to change your data model.  There are a numerous ways you can attempt to version your API.

I’d recommend having a listen to Sebastien Lambla (SerialSeb) talk on “Versions are Evil How to do Without in your API“.

Resources not Objects

I think of resources in an Web API as being about features or capabilities rather than objects.

For example, say this was our product data model:

When thinking about a product as a resource, I would likely want to more data.  I tend to drive a resource by the consumer.

Our backing model likely has other related data.  For example, a product may have a “AvailableToPromise” field which indicates available quantities.

So now our Product resource is starting to diverge from our data model.

CQRS

I tend to follow a CQRS style approach to Web API’s. For me, commands and queries are resources.

In regards to a Product, we likely have the ability to do some sort of Inventory Adjustment (command).  I would expose the Inventory Adjustment command as an endpoint and provide that endpoint with our Product Resource.

This way the consumer can start navigating and sees other available resources.

Comments

Web API’s and hypermedia are something I’m trying to understand more of and how I can create better Web API’s.

Let me know if you have any comments related to Web API’s either in comments or on twitter.


.NET CLI Basics

I started looking at the .NET Core CLI (Command Line Interface) a bit more over past couple weeks and figured I’d put together a blog and video covering the basics.

I’m intentionally covering only the basics because the CLI is currently at “Preview 2” and is not yet RTM.

Also, since we know the project.json is being eliminated before RTM, I didn’t want to dig into aspects like multi targeting different platforms and frameworks since that requires the project.json.

Video Walk Through

I’ve created a short video which explains everything this post will, so if you prefer video walk through this is for you:

.NET Core SDK

The first thing you need is the .NET Core SDK for Windows.  The new vanity domain for .Net is now dot.net

If you head on over there, you can download .NET Core SDK for Windows.

There are a other downloads on this page, specifically you can get the Visual Studio Update which will include .NET Core.  For the purpose of my example, since the intent is NOT to use full blown Visual Studio, just download the .NET Core SDK For Windows.

You can install the SDK with all the defaults.

Help

The easiest way to get usage information on the CLI and various commands is with

--help

.NET CLI

From here you can see all the common commands.  For each command, you can generally type “dotnet [command] –help” to get usage infromation about a specific command.

New

An example of this would be for the “new” command.  The new command creates the required files for a new .NET Core project.  Basically creating scaffolding for your new project.  If you are familiar with Yeoman, this is similar.

To get usage information on the “new” command we would type:

dotnet new --help

.NET CLI New Command

Restore

Since .NET Core is package based with NuGet, the natural next step is to restore all the NuGet packages for your new project.

This command is basically using NuGet under the hood.

You can specify where the restored packages will be placed but by default the .nuget/packages directory in your users home directory will be used for caching.

In my case, on my local machine this would be:

C:\Users\Derek\.nuget\packages

Run

Once you’ve restored all your dependencies, you can now run your app.

The run command is just a shortcut for building and executing your application in one step.  The run command uses the build command prior to launching your application.

The run command is used in the context of your project directory and not the built output in your bin directory.  Meaning you would run “dotnet run” from your project directory.

C:\Users\Derek\HelloWorld>dotnet run

If you wanted to run the HelloWorld.dll in your bin directory, you would execute:

C:\Users\Derek\HelloWorld>dotnet bin/HelloWorld.dll

Build

As you can expect this builds your application into Intermediate Language (IL) in the form of a DLL.

Even if you are creating a .NET Core console application, it will not generate an EXE by default.

An EXE would be generated if you are creating a self-contained .NET Core application, but by default the build process creates a portable application (dll) which can be run by any maching that has .NET Core installed.
Let me know if you have any comments and interesting experiences with the .NET CLI via Twitter or the comments section on my site or YouTube.


Getting Started with ASP.NET Core and VS Code

I recently presented at the Windsor-Essex .NET Developers group on getting started with ASP.NET Core and VS Code.  The intent was just to show how you can step outside of Visual Studio and create a Hello World application using the .NET Core CLI and VS Code.

Video Walk Through

I’ve created a short video which explains everything this post will, so if you prefer video walk through this is for you:

5 Easy Steps

For the purpose of my demo, I was using Windows.  I plan on creating a similar video for if you are on Mac or Linux, so if you are, stay tuned for those.  If you are Windows, it’s really easy to get started.

.NET Core SDK

The first thing you need is the .NET Core SDK for Windows.  The new vanity domain for .Net is now dot.net

If you head on over there, you can download .NET Core SDK for Windows.

There are a other downloads on this page, specifically you can get the Visual Studio Update which will include .NET Core.  For the purpose of my example, since the intent is NOT to use full blown Visual Studio, just download the .NET Core SDK For Windows.

You can install the SDK with all the defaults.

VS Code

Next is getting VS Code (Visual Studio Code).  Head on over to https://code.visualstudio.com and download the latest.

VS Code is on a monthly release cadence and is improving greatly with each release.  I’m enjoying it so much I’ve turned it into my default text editor.

You can install VS Code with all the defaults.

.NET Core CLI

The Command Line Interface (aka CLI) is new to .NET Core.  The CLI gives you the ability to create new projects (think yeoman), build/compile, run, package and more.

To create a new ASP.NET Core application, in a new empty folder, from the command prompt or powershell:

dotnet new -t web

This will create a new ASP.NET web application template with all the necessary files.

the “-t web” portion of the command is specifying that you want to generate an application using the web template.

In the new world of .NET Core, everything is packaged via NuGet.  Because of this, you need to download all the relevant packages for the ASP.NET Core.

dotnet restore

This will download and cache all the nuget packages.  If you run this again, it will not re-download from the internet as there are local cached copies.

VS Code

Now that you have a new project setup, open up VS Code in the folder of your new project.  If you are on the command prompt still you can simply type:

code .

Once VS Code opens, it will notice you have a C# project.  After a several seconds there will be a dialog at the top:

“Required assets to build and debug are missing from your project.  Add them?”

This is asking you to install the C# (Omnisharp) extension.  Click Yes to have it installed.

ext

Once installed, if you open up any .cs file, you will see in the status bar that it recognizes its a C# file and there is a fire icon which means Omnisharp is running. You will also notice your file has syntax highlighting, intellisense and more.

fire

Debugging

You are now completely setup to start debugging and running your ASP.NET Core app in VS Code.  You can create a breakpoint and start debugging by clicking on the debug icon in the left nav.  You will now see a familiar green arrow which allows you to start running your application in debug mode.

debug

That’s it!

Getting started with ASP.NET Core and VS Code is pretty straight forward.  I’m looking forward to everything else in store for VS Code, however Omnisharp is a big part of the experience.  If you prefer another editor take a look at http://www.omnisharp.net to get started with other editors on other platforms.

Let me know if you have any comments and interesting experiences with ASP.NET Core or VS Code via Twitter or the comments section on my site or YouTube.