Defining routes with Superscribe simple-syntax

As mentioned in the previous section, defining routing using the fluent API is not ideal for a number of reasons. Built on top of the fluent API is a simple domain specific language... valid C# code made using a combination of lambdas, casts and operator overloads.

The simple-syntax provided by Superscribe is designed to be terse and minimal, so you can get on with the important business of designing your routes. In this section we'll translate an example from the Fluent Api to use the simple-syntax, stage by stage to show which statements are equivilent.

The .Route family

When using the Fluent API, we defined routes by manually instantiating subclasses of GraphNode, created edges with Slash() and then attached them to the base node using .Base() and .Zip():

    var engine = RouteEngineFactory.Create();

    var helloRoute = new ConstantNode("Hello").Slash(new ConstantNode("World"));
    helloRoute.FinalFunctions.Add(new FinalFunction("GET", o => "Hello World"));

    engine.Base.Zip(helloRoute.Base());

    // "/Hello/World" -> "Hello World"
        

First of all, Superscribe provides a shorthand way of attaching routes to the base node using the .Route method:

    // engine.Base.Zip(helloRoute.Base()); becomes ->
    engine.Route(helloRoute);
        

As well as being slightly shorter, this method will also call .Base for us. So far so good, but it isn't much of an improvement... we can still do a bit more. To apply a final function matching the 'GET' method, we can supply it as an argument to one of .Route's sister methods:

    
    var engine = RouteEngineFactory.Create();

    var helloRoute = new ConstantNode("Hello").Slash(new ConstantNode("World"));
    engine.Get(helloRoute, o => "Hello World");

    // "/Hello/World" -> "Hello World"
        

.Get performs the same function as .Route but will also add our final function to the end of the chain, and apply the 'GET' modifier to it. Superscribe provides methods for each of the main Http Methods - GET, POST, PUT, PATCH and DELETE. You'll only really want to use .Route if the framework you're using to handle requests also takes care of Http Methods for you (such as Web Api).

Shorthand operators

Instead of calling .Slash we can use the shorthand operator '/':

    
    var engine = RouteEngineFactory.Create();

    var helloRoute = new ConstantNode("Hello") / new ConstantNode("World");
    engine.Get(helloRoute, o => "Hello World");

    // "/Hello/World" -> "Hello World"
        

Next up, an implicit cast from string to GraphNode provides a way to simplify the instantiation of our constant nodes:

    
    var engine = RouteEngineFactory.Create();
    engine.Get(r => r / "Hello" / "World", o => "Hello World"));

    // "/Hello/World" -> "Hello World"
        

When calling any of the methods in the .Route family though, we sometimes encounter a problem. In order to use the Superscribe shorthand operators, at least one of the operands must be a GraphNode.

In the above example, we solve this by using an overload that takes a lambda with an 'r' parameter. This parameter represents the base node, and so allows the operator chain to resolve itself succesfully. This overload is available to every method in the .Route family.

Finally for this example, Superscribe has one more trick up it's sleeve. Another overload takes a traditional string-based route, parses it, and creates a graph for us. This gives us a really concise final route definition that still behaves exactly like the original:

    
    var define = RouteEngineFactory.Create();
    define.Get("Hello/World", o => "Hello World"));

    // "/Hello/World" -> "Hello World"
        

Note that here we've renamed the 'engine' variable to 'define' which gives us the added bonus of reading really nicely. This is optional of course.

GraphNode shorthands

Creating a ConstantNode from a string isn't the only way we can take advantage of casting to build routes. In the Fluent API section we demonstrated how Superscribe capture parameters using ParamNode<T>:

    var engine = RouteEngineFactory.Create();

    var helloRoute = new ConstantNode("Hello").Slash(new ParamNode<string>("Name"));
    helloRoute.FinalFunctions.Add(new FinalFunction("GET", o => "Hello " + o.Parameters.Name));

    engine.Base.Zip(helloRoute.Base());

    // "/Hello/Kathryn" -> "Hello Kathryn"
        

Now here's the simple-syntax version:

    
    var define = RouteEngineFactory.Create();
    define.Get("Hello" / (String)"Name", o => "Hello " + o.Parameters.Name);

    // "/Hello/Kathryn" -> "Hello Kathryn"
        

The Superscribe String class derives from ParamNode<string> and adds an extra explicit cast operator, the sole purpose of which is to provide us with this much nicer syntax. There are other such shorthands for each of the primary data types supported by Superscribe:

• Integer (Int)
• Long (Long)
• String (String)
• Boolean (Bool)

And of course, because all Superscribe nodes are strongly typed and derive from GraphNode, it's easy to create our own shorthands. Here's an example for Guid:

    public class GuidNode : ParamNode<Guid>
    {
        public GuidNode(string name) : base(name) { }

        public static explicit operator GuidNode(string name)
        {
            return new GuidNode(name);
        }
    }
        

Beyond the basics

Using the Fluent API and the .Zip function we were able to compose our route graph by combining several complete routes. This still works when using the simple-syntax, as each call to one of the .Route family of methods will automatically call .Zip for us. This is demonstrated in this example modified from one of the Web Api samples:

    var define = RouteEngineFactory.Create();
    
    define.Get ("api" / "Blogs" / (Int)"blogid" / "Posts", o => // Handle blogposts get...);
    define.Post("api" / "Blogs" / (Int)"blogid" / "Posts", o => // Handle blogposts post...);
    define.Get ("api" / "Blogs" / (Int)"blogid" / "Tags",  o => // Handle blogtags get...);
    define.Post("api" / "Blogs" / (Int)"blogid" / "Tags",  o => // Handle blogtags post...);
        

There's another way of achieving this same result. As all route definitions in Superscribe are strongly typed, it's possible to assign routes or parts of routes to variables which allow us to re-use compose definitions in useful and interesting ways:

    var define = RouteEngineFactory.Create();
    
    var blog = define.Route("api" / "Blogs" / (Int)"blogid");

    define.Get (blog / "Posts", o => // Handle blogposts get...);
    define.Post(blog / "Posts", o => // Handle blogposts post...);
    define.Get (blog / "Tags",  o => // Handle blogtags get...);
    define.Post(blog / "Tags",  o => // Handle blogtags post...);
        

Note also how we're defining the re-usable component of our route definitions using the original .Route method as it allows us to define a route with no Final Functions or method modifiers.

Replacing Asp.Net Web Api routing with Superscribe

Ask most developers what could be improved about Asp.Net Web Api and they'll probably mention the routing. This has been improved considerably by the introduction of attribute routing in Web Api 2, but attribute routing isn't for everyone. Some like to define all the routes for an application in one place. Superscribe.WebApi allows us to define routes centrally using Supersribe simple-syntax and a few Web Api specific nodes.

Controller Selection

The following route recreates the behavior of the default rouing you get when creating a new project:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            var define = SuperscribeConfig.Register(config);
            define.Route("api" / Any.Controller / (Int)"id");
        }
    }
        

Here we've used a Web Api specific node provided by a static constructor property called Any.Controller. This node will match any alpha numeric segment, and then add an entry to the RouteData environment dictionary accordingly. Once route parsing has completed succesfully, Superscribe will pass this value and any parameters across to Asp.Net and then the process of selecting an action continues as per normal (You can view a summary of this logic here)

Web Api is still doing the bulk of the work, Superscribe is just passing it the information it needs; as a result we don't usually need to specify a Final Function for our nodes. We can still do this if we want to, but we don't have as much flexibility with the Response as we do when responding to a route directly.

Custom Controller Mappings

Suppose our controller name doesn't match the format "<segment>Controller". In this case we can match a specific segment value and set the controller name ourselves by providing it's actual name as a parameter to the .Controller shorthand:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            var define = SuperscribeConfig.Register(config);

            define.Route("api" / "Blogs".Controller());
            define.Route("api" / "Blogs".Controller() / (Int)"id");
            define.Route("api" / "Blogs" / (Int)"id" / "Tags".Controller("BlogTags"));
        }
    }

    // /api/Blogs/
    // /api/Blogs/123/
    // /api/Blogs/123/Tags
        

By using the .Controller shorthand syntax with "Blogs" as our first node, we change the behavior from a regex match to a literal comparison. Superscribe will still use the segment value to set the Controller name but the matching process in this case will be much faster.

By using .Route directly instead of .Get or .Post etc we ensure that the built in Action Selection logic in Web Api will be able to work correctly for any Http Method, although you can still use these to be more selective with matching if required.

The above example uses three seperate calls to .Route, for ease of understanding, however the same route graph can be constructed using a single line. You may not choose to use this approach in a line of business application, but it can be useful when hacking things together:

    define.Route("api" / "Blogs".Controller() / (Int)"id" / "Tags".Controller("BlogTags"));
        
    // /api/Blogs/
    // /api/Blogs/123/
    // /api/Blogs/123/Tags
        

This works because the Web Api handler that Superscribe uses does not care which node route matching finishes on, so long as it has consumed all the route segments. It is up to Web Api itself to determine if the route maps to a valid controller/action based on the information given to it.

You'll also notice that the definition contains two instances of te .Controller shorthand. This is also not a problem as if the route matching process reaches the second "Tags" controller node, this will simply overwrite the Controller set by the previous node before it gets passed to Web Api.

Action Selection

Any.Controller has a partner in crime in the form of Any.Action. This behaves in the same way as it's counterpart but instead it adds an entry to the RouteData enivonment dictionary which tells Web Api explicitly which action to select.

In this example we have a controller called products that handles read only resources for a few categories. There aren't many of them and they're all bespoke so rather than having seperate controllers, we just want to hard code an action for each:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            var define = SuperscribeConfig.Register(config);
            define.Get("api" / "Products".Controller() / Any.Action() / (Int)"id");
        }
    }
      

We can also match literals and choose an action in situations where the segment does not directly match the action name. This works in a similar way to the controllers example above, but with the key difference that the action name is set via a shorthand Final Function:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            var define = SuperscribeConfig.Register(config);

            define.Get("api" / "Products".Controller());
            define.Get("api" / "Products".Controller() 
                                / "BestSellers", To.Action("GetBestSellers"));
            define.Get("api" / "Products".Controller() 
                                / "TopTen", To.Action("GetTopTen"));
        }
    }

    // /api/Products
    // /api/Products/BestSellers
    // /api/Products/TopTen
      

To.Action() provides a ready made Final function that will set the action name explicitly. Using a Final Function in this way encourages readability of routes and prevents the developer from creating spaghetti like definitions that are hard to reason about.

Actions and Http Methods

Most of the time you don't need to choose actions explicity, however there are some situations where Web Api is not able to figure things out for itself and Superscribe provides an easy way for us to give it a helping hand.

One example of this when using traditional Web Api routing is when trying to cater for multiple actions that handle the same verb within a single controller, particularly with multiple collection resources. If the method signatures of our actions contain the same parameters, then Web Api cannot tell them apart and will throw an ambiguous match exception.

By using the .Route family of methods to controll the Http Methods assocaited with the Final Functions that set our actions, we can achieve a much finer level of control while still keeping our route definitions terse and maintainable:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            var define = SuperscribeConfig.Register(config);

            var blogs = define.Route("api" / "Blogs".Controller() / (Int)"blogid");

            define.Get(blogs / "Posts", To.Action("GetBlogPosts"));
            define.Get(blogs / "Tags", To.Action("GetBlogTags"));

            define.Post(blogs / "Posts", To.Action("PostBlogPost"));
            define.Post(blogs / "Tags", To.Action("PostBlogTag"));
        }
    }

    // GET ->  /api/Blogs
    // GET ->  /api/Blogs/1
    // GET ->  /api/Blogs/1/Posts
    // GET ->  /api/Blogs/1/Tags
    // POST -> /api/Blogs/1/Posts
    // POST -> /api/Blogs/1/Tags
        

Handling routes with Modules in Asp.Net Web Api

Asp.Net Web Api uses controllers and actions because it was originally derived from the MVC framework and although things have moved on since then, it still shares some of the same constructs. With Superscribe we are free to break away from these restrictions and handle our routes using whatever classes we wish.

Superscribe allows you to do this in the form of modules, a great web app construct inspired by the Ruby web framework Sinatra and the .Net framework NancyFX.

Assembly Scanning

When the module configuration is activated on app startup, Superscribe scans your assemblies for classes that derive from SuperscribeModule and then instantiates them in turn. All route handlers for modules are defined in the constructor, so this process results in all of our route definitions being added to the graph.

Modules can be enabled in Superscribe.WebApi with the following config:

    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            SuperscribeConfig.RegisterModules(config);
        }
    }
        

A basic module takes the following form:

    public class HelloWorldModule : SuperscribeModule
    {
        public HelloWorldModule()
        {
            this.Get["/"] = o => "Hello World!";
        }
    }
        

The primary difference when routing with modules compared to traditional Web API is that we don't get any of the action selection logic that maps requests to actions, so we have to be prescriptive about our http methods and every definition must be assigned a final function.

In addition to Get[], SuperscribeModule also exposes properties for Put, Post, Patch and Delete methods. Each one takes an indexer within which we can use the Superscribe simple-syntax. As you can see in this example, we are using the Get indexer to configure our app respond to the "/" route.

Building the Route Graph

Just like when we defined routes using the .Route family of methods, to build complex definitions we have to repeat parts of the route for some handlers:

    public class HelloWorldModule : SuperscribeModule
    {
        public HelloWorldModule()
        {
            this.Get["Hello/World"] = o => "Hello World!";

            this.Get["Hello" / (String)"Name"] = o => "Hello " + o.Parameters.Name;
        }
    }
        

Each call to this.Get, or any of the other method helpers ensures that the route graph is still constructed efficiently. Behind the scenes each route is 'Zipped' together (see the Fluent Api section) so that equivilent nodes will be merged. In the above example, we end up with a single "Hello" node with two edges.

Model Binding and Dependencies

When we configured routes using the Fluent Api or the simple-syntax, we accessed parameters in our Final Function via the RouteData object and it's Parameters dictionary. We've still got that feature within our modules, and in fact the route data object contains a few helper methods that give us the ability to do things in Web Api that controller/action selection would usually take care of.

The first of these is model binding - taking data from the request body or querystring and mapping it to a strongly typed model. We're still working on top of Web Api behind the scenes so Superscribe provides the ability to invoke the standard model binder via the .Bind function:

    public class ProductsModule : SuperscribeModule
    {
        public ProductsModule()
        {
            this.Post["Produts"] = o => 
            {
                var model = o.Bind<Product>();               
                // do something with product
            }
        }
    }
        

Secondly, if we want to actually store our Product then we also need to access the database, and the best way to do that and keep things loosely coupled is to inject a dependency. For that we can use the .Require function which when used with Web Api modules is just a wrapper for the standard Web Api DepedencyResolver:

    public class ProductsModule : SuperscribeModule
    {
        public ProductsModule()
        {
            this.Post["Produts"] = o => 
            {
                var repository = o.Require<IProductsRepository>();
                var model = o.Bind<Product>();
                repository.create(model);

                return new HttpResponseMessage(HttpStatusCode.Created);
            }
        }
    }
        

Now we've got all the ingredients we need to build our app using modules. Web Api is still taking care of content negotiation for us and we can easily build in other aspects such as validation as needed. We can also take control over the response as we need to by returning HttpResponseMessage just as we would in a regular controller.

Owin Middleware Routing and Request Handling

Superscribe introduces the concept of routing as middleware - for Owin that means you can add the Superscribe Route middleware into your application to perform routing for you and then re-use the results anywhere in your application.

    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var define = OwinRouteEngineFactory.Create();
            var httpconfig = new HttpConfiguration();
            
            SuperscribeConfig.RegisterModules(httpconfig, define);

            define.Route("Values".Controller());
            
            app.UseSuperscribeRouter(define)
                .UseWebApi(httpconfig)
                .WithSuperscribe(httpconfig, define);
        }
    }
        

    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var httpconfig = new HttpConfiguration();
            httpconfig.Routes.MapHttpRoute(
                "DefaultApi", "api/webapi/", new { controller = "Hello" });

            var define = OwinRouteEngineFactory.Create();

            // Set up a route that will forward requests to either web api or nancy
            define.Pipeline("api/webapi").UseWebApi(httpconfig);
            define.Pipeline("api/nancy").UseNancy();
            
            app.UseSuperscribeRouter(define);
        }
    }
        

    public class Startup
    {
        public void Configuration(IAppBuilder appBuilder)
        {
            var engine = OwinRouteEngineFactory.Create();

            var httpconfig = new HttpConfiguration();
            SuperscribeConfig.Register(httpconfig, engine);

            engine.Route("Values".Controller());
            engine.Route("Api" / "Values".Controller());

            engine.Pipeline("Api").Use<ApiDependencies>();

            appBuilder.UseAutofacContainer(this.RegisterServices())
                .UseSuperscribeRouter(engine)
                .UseWebApiWithContainer(httpconfig)
                .WithSuperscribe(httpconfig, engine);
        }
    }
        

    public class ValuesController : ApiController
    {
        private readonly IRepository repository;

        public ValuesController(IRepository repository)
        {
            this.repository = repository;
        }

        public IEnumerable<string> Get()
        {
            return this.repository.Values();
        }
    }

    // /Values ->       ["value1","value2"]
    // /Api/Values ->   ["value3","value4"]
        

    public class ApiDependencies
    {
        private readonly Func<IDictionary<string, object>, Task> next;

        public ApiDependencies(Func<IDictionary<string, object>, Task> next)
        {
            this.next = next;
        }

        public async Task Invoke(IDictionary<string, object> environment)
        {
            var container = environment.GetRequestContainer() as ILifetimeScope;
            var newBuilder = new ContainerBuilder();
            newBuilder.RegisterType<ApiRepository>()
                   .As<IRepository>()
                   .InstancePerLifetimeScope();

            newBuilder.Update(container.ComponentRegistry);

            await this.next(environment);
        }
    }
        

    public class AddName
    {
        private readonly Func<Dictionary<string, object>, Task> next;

        public AddName(Func<IDictionary<string, object>, Task> next)
        {
            this.next = next;
        }

        public async Task Invoke(IDictionary<string, object> environment)
        {
            var parameters = environment["route.Parameters"] as IDictionary<string, object>
            if (parameters != null && parameters.ContainsKey("Name"))
            {
                await environment.WriteResponse("Hello " + parameters["Name"]);    
            }
        }
    }
        

    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var engine = OwinRouteEngineFactory.Create();

            app.UseSuperscribeRouter(engine)
                .Use<AddName>();
        }
    }
        

    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var define = OwinRouteEngineFactory.Create();            
            define.Route("Hello/World", o => "Hello World");
            
            app.UseSuperscribeRouter(define)
                .UseSuperscribeHandler(define);
        }
    }
        

    var options = new SuperscribeOwinOptions();
    options.MediaTypeHandlers.Add("application/json", new MediaTypeHandler
    {
           Write = (env, o) => env.WriteResponse(JsonConvert.SerializeObject(o)),
           Read = (env, type) =>
           {
               object obj;
               using (var reader = new StreamReader(env.GetRequestBody()))
               {
                   obj = JsonConvert.DeserializeObject(reader.ReadToEnd(), type);
               };

               return obj;
           }
       });

    var engine = OwinRouteEngineFactory.Create(options);

    app.UseSuperscribeRouter(engine)
        .UseSuperscribeHandler(engine);
        

     public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var options = new SuperscribeOwinOptions();
            options.MediaTypeHandlers.Add("application/json", new JsonMediaTypeHandler();

            var engine = OwinRouteEngineFactory.Create(options);

            app.UseSuperscribeRouter(engine)
                .UseSuperscribeHandler(engine);
        }
    }
        

    public ProductsModule()
    {
        this.Get["Products"] = o => products;

        this.Get["Products" / (Int)"Id"] = o => 
            products.FirstOrDefault(p => o.Parameters.Id == p.Id);

        this.Get["Products" / (String)"Category"] = o => 
            products.Where(p => o.Parameters.Category == p.Category);

        this.Post["Products"] = o =>
            {
                var product = o.Bind<Product>();
                return new { Message = string.Format(
                    "Received product id: {0}, description: {1}", 
                    product.Id, product.Description) };
            };
    }