Versioning WebApi and documenting version with Swagger

Versioning in WebApi

Note: This post draws alot of points from https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/ – but is more about implementation and documentation through swagger.
So please go read Troy’s post and then come back :).
There are a couple of ways of versioning a restful api
among them are:
1. Url versioning e.g. GET http://example.com/api/v1/cars
2. Request-Header e.g. GET http://example.com/api/cars — Header: api-version: 1
There are pros and cons in both regards, Troy gets around them quite nicely.
Time to code!

Url Versioning

Easy – simply use either the RoutePrefix- or RouteAttribute

Read more about the Routing-Attribute here

Request-Header

Drawing from Troy’s post
We create a new attribute which uses a custom routing constraint

** Usage **

Effectively matching routes based on the “api-version” header.

Swagger

When using swashbuckle (swagger implementation for .Net).
It knows about the default Route- and RoutePrefixAttribute, so Url Versioning is taken care of, out of the box.
But Header versioning is not.
Fortunately, it’s quite easy to implement an OperationFilter that adds the header as a parameter to the endpoints in question.
This implementation uses a list of versions and the endpoints relativepaths to know when to add the parameter and when not to.


How would you implement the OperationFilter?

Showing messages to users with Toastr and SignalR, the perfect match.

Toastr
Sending updates/messages to users can sometimes be a pain in the butt, but using signalR can provide an enormous relief to exactly this matter.
Often times one would have a controller method which would return some sort of JsonResult (or View) containing whether or not the transaction went well. Using SignalR in conjunction with Toasts, we can write an a single implementation that will work for all of your future actions as well.
No more coding ajax success/failure for every single action.

Prerequisites:

  1. An MVC Project
  2. A BaseController
  3. SignalR package from nuget
    • Install-Package Microsoft.AspNet.SignalR
  4. A Toast implementation
    • //cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/js/toastr.min.js
      //cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/css/toastr.min.css
  5. A razor _layout

Once you have everything installed and up and running you are ready to implement SignalR

SignalR Backend implementation

Once the package is installed it should create a startup.cs file – if it doesn’t go create one.
It should look like this

Now we are ready to create the Hub. In SignalR the hub is what ties together connections and messages sent.

Once done, create a MessageEmitter – this will send Toasts through SignalR

Notice I’m using an enum for ToastType

Now we are about ready to send Toasts to our users.

SignalR Frontend implementation

Now for the razor layout page.
Standard SignalR connection and then showing the toast when it is received.

Using this whole ordeal

To actually send a toast message to the user.
simply call the BaseController method from earlier ShowToastMessage()

What now?

You could implement a GlobalErrorHandler attribute and a custom ToastException to throw on controller errors.
it could look something like this


it would then be used by throwing a new ErrorToast, which in turn would send an error HTTP status code (500) to the client AND show an error Toast.
You can now handle ajax errors, along with successes.

jquery – cycle through classes on click

Imagine this

we have a nice little bootstrap panel, or maybe a few of them…
ermahgerd bootstrap
now let’s imagine that we’d like to change the width of the panel according to bootstrap standards.
you would do this by changing the col-* to something else.
One thing we could do is to use jquery’s toggleClass function.
https://gist.github.com/VisualBean/259551fdbc6c7d9193733cebc5d10fff
the above basically just switches between 2 classes (and ONLY 2 classes)
What if we want to cycle through say col-lg-4 then col-lg-8 then col-lg-12?
I started googling a bit and fell upon the following answer on stackoverflow.
What this basically does is get the current class from the array of cyclable classes then pick the next item in the array or the first. Usage:
Basic example
[codepen_embed height=”265″ theme_id=”0″ slug_hash=”xgwdLj” default_tab=”js,result” user=”visualbean”]See the Pen xgwdLj by Alex (@visualbean) on CodePen.[/codepen_embed]
Advanced panel example fiddle [codepen_embed height=”265″ theme_id=”0″ slug_hash=”NdGgrg” default_tab=”html,result” user=”visualbean”]See the Pen NdGgrg by Alex (@visualbean) on CodePen.[/codepen_embed]
Full credits to Aupajo