Tag Archives: Web API

Working with Non-Compliant OWIN Middleware

Microsoft.Owin, a.k.a. Katana, provides a number of very useful abstractions for working with OWIN. These types are optional but greatly ease the construction of applications and middleware, especially security middleware. The Katana team did a great job of ensuring their implementations work well with Microsoft.Owin as well as the standard OWIN MidFunc described below. However, not all third-party middleware implementations followed the conventions set forth in the Katana team’s implementations. To be fair, OWIN only standardized the middleware signature earlier this year, and the spec is still a work in progress.

At some point in the last year, I discovered the HttpMessageHandlerAdapter was not, in fact, OWIN compliant. I learned from the Web API team they would not be able to fix the problem without introducing breaking changes, so I came up with an adapter that should work with most implementations based on OwinMiddleware that didn’t expose the OWIN MidFunc.

The solution is rather simple, and the Katana source code provides one of the necessary pieces in its AppFuncTransition class. The adapter wraps the OwinMiddleware-based implementation and exposes the OWIN MidFunc signature. After creating the adapter specifically for HttpMessageHandlerAdapter, I created a generic version I think should work for any OwinMiddleware. (Examples in both C# and F#.)


using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using AppFunc = Func<IDictionary<string, obj>, Task>;
using MidFunc = Func<AppFunc, AppFunc>;
public class MidFuncType
{
private readonly AppFunc next;
public MidFuncType(AppFunc next)
{
this.next = next;
}
public Task Invoke(IDictionary<string, obj> environment)
{
// invoke the middleware, call `next`, etc.
// return the `Task`
return Task.FromResult<obj>(null) :> Task
}
}

view raw

MidFuncAsClass.cs

hosted with ❤ by GitHub


open System
open System.Collections.Generic
open System.Threading.Tasks
type AppFunc = Func<IDictionary<string, obj>, Task>
type MidFunc = Func<AppFunc, AppFunc>
type MidFuncType(next: AppFunc) =
// set up the middleware
member this.Invoke(environment: IDictionary<string, obj>) : Task =
// invoke the middleware, call `next`, etc.
// return the `Task`
Task.FromResult<obj>(null) :> Task

view raw

MidFuncAsType.fs

hosted with ❤ by GitHub


using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Owin;
using System.Web.Http.Owin;
using AppFunc = Func<IDictionary<string, obj>, Task>
/// See https://katanaproject.codeplex.com/SourceControl/latest#src/Microsoft.Owin/Infrastructure/AppFuncTransition.cs
internal sealed class AppFuncTransition : OwinMiddleware
: base(null)
{
private readonly AppFunc next;
public AppFuncTransition(next: AppFunc)
{
this.next = next;
}
public Task Invoke(IOwinContext context)
{
// TODO: check for null
return this.next(context.Environment)
}
}
/// Explicit wrapper for HttpMessageHandlerAdapter
public class OwinMessageHandlerMiddleware
{
private readonly OwinMiddleware next;
OwinMessageHandlerMiddleware(AppFunc next, HttpMessageHandlerAdapterOptions /* I think this is the right name */ options)
{
var nextKatana = new AppFuncTransition(next);
this.next = new HttpMessageHandlerAdapter(nextKatana, options);
}
public Task Invoke(IDictionary<string, obj> environment)
{
// TODO: check for null
var context = new OwinContext(environment);
return next(context);
}
}
// This can be made generic:
/// Generic OwinMiddleware adapter
public abstract class OwinMiddlewareAdapter
{
private readonly OwinMiddleware next;
protected OwinMiddlewareAdapter(AppFunc next, Func<OwinMiddleware, OwinMiddleware> factory)
{
var nextKatana = new AppFuncTransition(next);
this.next = factory(nextKatana);
}
public Task Invoke(IDictionary<string, obj> environment)
{
// TODO: check for null
var context = new OwinContext(environment)
return next(context)
}
}
/// HttpMessageHandlerAdapter using the Generic OwinMiddleware adapter
public class OwinMessageHandlerMiddlewareAdapter : OwinMiddlewareAdapter
{
public OwinMessageHandlerMiddlewareAdapter(AppFunc next, HttpMessageHandlerAdapterOptions /* I think this is the right name */ options)
: base(next, m => new HttpMessageHandlerAdapter(m, options))
{
}
}

view raw

OwinMessageHandlerAdapter.cs

hosted with ❤ by GitHub


open System
open System.Collections.Generic
open System.Threading.Tasks
open Microsoft.Owin
open System.Web.Http.Owin
type AppFunc = Func<IDictionary<string, obj>, Task>
/// See https://katanaproject.codeplex.com/SourceControl/latest#src/Microsoft.Owin/Infrastructure/AppFuncTransition.cs
[<Sealed>]
type AppFuncTransition(next: AppFunc) =
inherit OwinMiddleware(null)
default x.Invoke(context: IOwinContext) =
// TODO: check for null
next.Invoke(context.Environment)
/// Explicit wrapper for HttpMessageHandlerAdapter
type OwinMessageHandlerMiddleware(next: AppFunc, options) =
let nextKatana = AppFuncTransition(next) :> OwinMiddleware
let webApiKatana = new HttpMessageHandlerAdapter(nextKatana, options)
member x.Invoke(environment: IDictionary<string, obj>) =
// TODO: check for null
let context = new OwinContext(environment)
webApiKatana.Invoke(context)
// This can be made generic:
/// Generic OwinMiddleware adapter
type OwinMiddlewareAdapter(next: AppFunc, factory: Func<OwinMiddleware, OwinMiddleware>) =
let nextKatana = AppFuncTransition(next) :> OwinMiddleware
let middlewareKatana = factory.Invoke(nextKatana)
member x.Invoke(environment: IDictionary<string, obj>) =
// TODO: check for null
let context = new OwinContext(environment)
middlewareKatana.Invoke(context)
/// HttpMessageHandlerAdapter using the Generic OwinMiddleware adapter
type OwinMessageHandlerMiddlewareAdapter(next: AppFunc, options) =
inherit OwinMiddlewareAdapter(next, (fun m -> new HttpMessageHandlerAdapter(m, options) :> _))

view raw

OwinMessageHandlerMiddleware.fs

hosted with ❤ by GitHub

I hope that helps someone else. If there’s interest, I can package this up and place it on NuGet, though it seems a lot of effort for something so small. The source code above is released under the Apache 2 license, in keeping with the use of AppFuncTransition used above from the Katana source.

Bundling and Minification with Web Essentials

Pta.Build.WebEssentialsBundleTask A few months ago, the Tachyus web application used a C# + F# web application approach to separate the front-end HTML, CSS, and JavaScript from the back-end F# ASP.NET Web API application. With this configuration, we introduced Web Essentials to bundle and minify our CSS and JavaScript at build time within Visual Studio. To simplify deployments and better group related and shared code, we decided to merge the back-end with another Web API application, which used the F# MVC 5 project template. We originally tried using CORS, which worked great in almost every environment. Unfortunately, the one environment in which we ran into trouble was our staging/production environment. Since we are building an internal-only API, we haven’t spent the extra effort to make our APIs evolvable; therefore, we decided to just merge all three projects together into the F# web project. This worked rather well, except for Web Essentials. We abandoned Web Essentials, as well as any form of bundling or minification at that time.

Fast forward to last week: we again split the front-end application out into a separate, C# project. We did this for several reasons:

  • We ran into trouble trying to remote debug the F# web project
  • The project had grown to the point that it was quite large, and it made sense to separate the two for maintenance
  • It’s common even in other languages to separate the front-end into a separate folder or project as different teams are often responsible for the different apps, which is not quite our case but close
  • We wanted to clean up our Angular code so that we had less Angular spread throughout and more standard JavaScript; for this we wanted to use bundling again

I was able to add Web Essentials back into the solution since we were again using a C# project. However, this had its own challenges, specifically in the form of communication to the rest of the team that they would need to install Web Essentials in order for their updates to take effect.

Fortunately, my colleague Anton Tayanovskyy recently found and pointed me toward the WebEssentialsBundleTask, which is a MSBuild task that will run the Web Essentials transformations at runtime depending on the build configuration, i.e. Debug or Release. This tool provides explicit script references for Debug builds and a bundled (and minified, if desired) version for Release builds. It seems to only require the presence of a Web Essentials-style .bundle file to work, so I would expect this to work equally well with a F#-only solution, though I have yet to try that. The WebEssentialsBundleTask has its own issues, though. It will modify your index.html file whenever it runs, so you must make sure to revert changes you don’t want to keep. We rarely change our index.html file since nearly everything is built in the form of Angular directives or templates. Nevertheless, you should consider the cost to your own project.

You may wonder why we didn’t just build a simple FAKE task. After all, whitespace in JavaScript is relatively meaningless, so a very simple concat + remove could probably get the job done, especially since we use ; where applicable. I definitely considered this option, as well as creating new FAKE tasks built around a node.exe using tools like grunt.js or gulp.js. In the end, these all seemed like overkill with the availability of Web Essentials, at least until we had evaluated whether WE would work for our purposes. We are still evaluating. What are you using? Did you find this helpful?

Web API and Dynamic Data Access

In .NET Rocks episode 855, Jeff Fritz commented on ASP.NET Web API being somewhat confusing in terms of its intended use. I don’t tend to agree, but I thought I would address one point he made in particular: that Web API is perhaps just another form of repository.

Web API is much more than a repository. And yes, it is indeed a protocol mapping layer. As Uncle Bob once noted, a web or api front end is just a mapping layer and is not really your application.

In many cases, however, one could argue that a web-api-as-repository is a fairly solid use case. OData is a great example. However, I was thinking of yet another argument I’ve heard for dynamic languages: when you are just going from web to database and back, you are not really working with types.

In that spirit, I set out to write a simple Web API using SQL and JSON with no explicit class definitions. You can see the results in this gist:

using System;
using System.Collections.Generic;
using System.Configuration;
using System.Data.SqlServerCe;
using System.Diagnostics;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using System.Web.Http;
using Dapper;
using Newtonsoft.Json.Linq;
namespace ConsoleApplication1
{
class Program
{
static void Main(string[] args)
{
Nito.AsyncEx.AsyncContext.Run(() => MainAsync(args));
}
static async Task MainAsync(string[] args)
{
var config = new HttpConfiguration();
WebApiConfig.Register(config);
using (var server = new HttpServer(config))
using (var client = new HttpClient(server))
{
client.BaseAddress = new Uri("http://localhost/&quot;);
var cts = new CancellationTokenSource();
var json = @"{""title"":""Task"",""description"":""The task"",""createdDate"":""" + DateTime.UtcNow.ToString() + "\"}";
var postRequest = new HttpRequestMessage(HttpMethod.Post, "/api/tasks")
{
Content = new StringContent(json, Encoding.UTF8, "application/json")
};
var postResponse = await client.SendAsync(postRequest, cts.Token);
Trace.Assert(postResponse.StatusCode == HttpStatusCode.Created);
var location = postResponse.Headers.Location.AbsoluteUri;
var getResponse = await client.GetAsync(location);
Trace.Assert(getResponse.StatusCode == HttpStatusCode.OK);
var getBody = await getResponse.Content.ReadAsAsync<JObject>();
dynamic data = getBody;
Trace.Assert((string)data.title == "Task");
}
Console.WriteLine("Press any key to quit.");
Console.ReadLine();
}
}
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
public class TasksController : ApiController
{
static string _connString = ConfigurationManager.ConnectionStrings["Database1"].ConnectionString;
public async Task<IEnumerable<dynamic>> GetAll()
{
using (var connection = new SqlCeConnection(_connString))
{
await connection.OpenAsync();
IEnumerable<dynamic> tasks = await connection.QueryAsync<dynamic>("select Id as id, Title as title, Description as description, CreatedDate as createdDate from Tasks;");
return tasks;
}
}
public async Task<dynamic> Get(int id)
{
using (var connection = new SqlCeConnection(_connString))
{
await connection.OpenAsync();
IEnumerable<dynamic> tasks = await connection.QueryAsync<dynamic>("select Id as id, Title as title, Description as description, CreatedDate as createdDate from Tasks where Id = @id;", new { id = id });
if (!tasks.Any())
throw new HttpResponseException(Request.CreateErrorResponse(HttpStatusCode.NotFound, "Task not found"));
return tasks.First();
}
}
public async Task<HttpResponseMessage> Post(JObject value)
{
dynamic data = value;
IEnumerable<int> result;
using (var connection = new SqlCeConnection(_connString))
{
await connection.OpenAsync();
connection.Execute(
"insert into Tasks (Title, Description, CreatedDate) values (@title, @description, @createdDate);",
new
{
title = (string)data.title,
description = (string)data.description,
createdDate = DateTime.Parse((string)data.createdDate)
}
);
result = await connection.QueryAsync<int>("select max(Id) as id from Tasks;");
}
int id = result.First();
data.id = id;
var response = Request.CreateResponse(HttpStatusCode.Created, (JObject)data);
response.Headers.Location = new Uri(Url.Link("DefaultApi", new { controller = "Tasks", id = id }));
return response;
}
}
}
view raw Program.cs hosted with ❤ by GitHub

I used Dapper to simplify the data access, though I just as well could have used Massive, PetaPoco, or Simple.Data. Mostly I wanted to use SQL, so I went with Dapper.

I also model bind to a JObject, which I immediately cast to dynamic. I use an anonymous object to supply the values for the parameters in the SQL statements, casting the fields from the dynamic object to satisfy Dapper.

All in all, I kinda like this. Everything is tiny, and I can work directly with SQL, which doesn’t bother me one bit. I have a single class to manage my data access and API translation, but the ultimate goal of each method is still small: retrieve data and present it over HTTP. That violates SRP, but I don’t mind in this case. The code above is not very testable, but with an API like this I’d be more inclined to do top level testing anyway. It’s just not deep enough to require a lot of very specific, low-level testing, IMHO.

Also, note again that this is just retrieving data and pushing it up through an API. This is not rocket science. An F# type provider over SQL would give a good enough sanity check. Why bother generating a bunch of types?

Which brings up another point for another post: what would I do if I needed to add some logic to process or transform the data I retrieved?

As a future exercise, I want to see what it would take to cap this with the Web API OData extensions. That could be fun.

Nested Controllers in the Latest Web API Source

I just happened to drop over to the ASP.NET Web Stack and noticed that nested controllers are now allowed in Web API! This is terrific news for you F# developers who, like me, think that grouping related functionality, including controllers, within modules is a convenient practice. Note, that this is only in the source. You won’t be able to update your NuGet packages to get this functionality, though it is easy to replace the offending DefaultHttpControllerTypeResolver with this updated copy:

Replace DefaultHttpControllerTypeResolver 
1

config.Services.Replace(typeof(IHttpControllerTypeResolver), new MyHttpControllerTypeResolver())

The Origin of RESTful URLs

For at least the past year, I have repeatedly found my appreciation for the literal offended by the term “RESTful URLs.” I recently spent a bit of time trying to explain how this term is oxymoronic on the Web API Forums. While URIs are important as a means of identifying unique resources, REST doesn’t specify any other requirements for URIs. I often note that a RESTful URI could be a GUID. While this is certainly not very meaningful to humans, it satisfies the REST constraints.

While pondering nested resources in Web API yet again, I realized where I think this term originates. Ruby on Rails used the term “RESTful routing” to describe their approach to building Controllers along the line of resources and using a convention to route controllers in a hierarchy based on the controller name. The goal, I think, was to correctly model and mount resources at unique URIs. However, you get what I would call “pretty URLs” for free.

If you use the term “RESTful URLs,” please stop. While RESTful Routing makes sense, RESTful URLs are just nonsense. Do use “RESTful Routing.” Do use “Pretty URLs.” Just don’t confuse your terms. Thanks!

New Names for Old Things

[This is the third in a series started long ago on the use of MVC for building web “applications”.]

I’m glad I’m only getting back to this series now. I’ve had an opportunity to build many more web applications and have a much better appreciation for the poor terminology used to define web applications. For starters, this MV? business silly. We’ll get to that.

I know I’m a bit of an extremist in some things. Specifically, I like things to mean what they mean. When we abuse terms, we don’t communicate well. REST. There, I said it. I feel better. Stop using the term. Most people have a wrong idea of what it means b/c of all the silliness that has been done in its name. I don’t claim to know exactly myself. I don’t think it’s possible to rescue the term from the abuses heaped upon it. There, you see? I’m an extremist.

Now that we’ve covered that, on to MVC. I’m not sure who decided this was an accurate description for what happens on the server-side of the web, but it’s just flat wrong. As noted previously, HTTP uses a functional interface. It’s an IO-bound Request -> Response function. Can you use patterns on either side to help maintainability? Certainly! Just don’t confuse things. Let’s start with Views.

Views

What is a view?

The [view or viewport] is responsible for mapping graphics onto a device.
A viewport typically has a one to one correspondence with a display surface
and knows how to render to it. A viewport attaches to a model and renders
its contents to the display surface. In addition, when the model changes,
the viewport automatically redraws the affected part of the image to reflect
those changes. […] there can be multiple viewports onto the same model and
each of these viewports can render the contents of the model to a different
display surface.

If a view was merely a serialization of a model, this would make sense for building web applications. Unfortunately, there’s a problem. The definition suggests that the view automatically updates whenever the model changes. How do you do that with HTTP? HTTP doesn’t define any mechanism for hooking up observation of a server model. Before you say JavaScript, consider first the current use of View, or even UI. People commonly mean HTML. HTML is not a UI. HTML is a serialization format. The client (normally a browser) must interpret that HTML. Many of you will remember when that wasn’t so standard.

Can we achieve MVC today? Possibly. You might be able to leverage web sockets to reach across a client/server architecture such as that presented by HTTP. However, you are more likely to find that “MVC” on the server is just limiting. You are typically better off building a sort of restricted data access service, a.k.a Web API (subtle hint). There’s really no point in trying to enrich a serialization format to make it work more like true MVC across the client and server.

Controllers

This is no different than routing. Instead of calling your Router a Controller, you split them up. However, most frameworks really just use the router as a top level dispatcher and the controller as a lower-level dispatcher. Otherwise, I’d say web frameworks stay a lot closer to the original meaning than a lot of the other MV? patterns. (Hence the ?, of course.)

Models

This really is the crux. HTML is a model. I noted this last time. It’s just a serialization of data you want displayed. It happens to be a lot richer, but it’s still just a data model. HTML is a great way to bootstrap an application that otherwise uses JavaScript as a model serialization format. If you want to disagree, ask why HTML5 removes the presentation elements. Why has layout and style moved to CSS? CSS and the browser define the actual rendering. In a no-script web application, you don’t have to build a view. You get it for free.

Conclusion

So what? Am I just ranting that I don’t like how people abuse terms? Possibly. However, I think this goes deeper. When you allow the slippery slope, you get caught on it, as well. It’s inevitable. The bigger, lurking danger is that we start to confuse useful patterns and use them in the wrong places. Many people use MVC frameworks today to build web APIs. However, that’s not MVC. So if you then switch to a desktop app to write MVC applications, you are either confused or delighted to find that it’s so much richer.

I don’t know what I would call what we build for the web; I know I wouldn’t call it MVC. In my experiments with Frank, I’ve found that writing simple functions and nesting them with rules makes a very easy mechanism for building web APIs. I think that would essentially just be a Command pattern. Simple, elegant, and very easy to understand. YMMV.

Web API RC Released

If you have been trying out ASP.NET Web API, you will be happy to know that the RC is finally available. No more struggling with building the sources yourself or fumbling with installing the nightlies to the GAC. Henrik has posted a few articles on the changes, as well as a follow up to using the nightlies with the RC release, if you must. One final note: the assembly names have changed, I assume to allow you to install the MVC4 for VS2010 alongside a VS11 installation, which was previously not possible.