Introduction

This article will provide some guidelines on how to integrate ApiFrame into ASP.NET Web API project. ApiFrame is a simple .NET library that provides support for implementing Web API security (HMAC Authentication), exception handling, and versioning of Web API methods. The library is like a plugin-component that you can easily integrate into your application. You will find the source code and information related to ApiFrame at this code project article.

I will walk you through a simple Web API sample application that implements POST and GET method for demonstrating Authentication, Authorization, Versioning and Exception Handling. Also, I will take you through how to consume the service from an API Client.

Guidelines: How to integrate API Frame in Web API Project

First, Let us create a sample application.

Open Visual Studio 2012

Create a new ASP.NET MVC 4 Web Application

Select Web API project template

Installation

To install ApiFrame, run the following command in the Package Manager Console

Alternate, the library can be referenced in your project through Nuget Package Manager. In the solution explorer, Select the Web API project -> Right click and Open “Manage Nuget Packages…” -> Search for “ApiFrame” online. You will get the following and Click the install button, this will add API frame to your project.

Configuration

If you are implementing Authentication and Authorization through ApiFrame, then it is required to implement the following interface in your application.

IApiInception

For demo purpose let’s do the following in the Web API Project

Create a new folder named “ApiFrameConfig”

Inside the new folder

Create a class “ApiInception” that Implements “IApiInception”

Create a class “ApiException” that implements “IApiException”

Implementing IApiInception

This interface exposes three methods. The implementation of GetApplicationToken()in you project depends on your business model. If you are exposing the API service to a number of customers then it is required to have an access token and a secret token attached to each customer. Generally, access token and secret token is created at the time of registration and the same is share with the customer for integrating the client application to communicate with the service. If the service is exposed to a single customer then this configuration can be added to Web.config file. AuthScheme is the Authorization Scheme, this can be a common label that you keep it Web.Config or if you would like to attach an abbreviated name for each of you customer then you can use this property. It’s up to your choice but this piece of information is also validated by the library. So, AuthScheme is another piece of information you will need to share with the client.

For the demo purpose, I have the following Implementation in my sample.

Authentication is based on username and password. Ideally, the below method in your project will call the service/data access layer to check if the given user name and password is valid. For implementing this method, an access token and a secret token should be attached to each existing user. If the username and password is valid then the method should returns a user token as shown in the code sample below. This user tokens are used for authorization purpose. It’s up to the client application to preserve the tokens and use it for issuing a subsequent request to access an authorized resource. ApiFrame supports Role based access in addition. The Role property can be empty if you application doesn’t use Roles based access.

The below method is for Authorization. ApiFrame calls this method on authorization by passing the access token of a user as a input parameter to the method. In the real application, this method should call a service or data access method to query the database to fetch the user details by access token. The method constructs a ApiUserToken with the user details and returns the token.

Implementing IApiException

Once, you have done implementing the interfaces, it is required to add the following configuration in the project to injects the implementation (dependencies) into the library. In the Global.asax file, Include the below code in the Application_Start()

Sample Web API methods

In you are interested in versioning you Web API methods, ApiFrame provides an option for versioning using MVC Areas or using namespace. Let’s try using Areas.

Create a new MVC Area and name it as “V1” and do the following configuration in WebApiConfig.cs file. That it’s, you are almost done with setting up versioning your web API methods and rest you will have to play with the routing.

Add a new controller to the project and name it “DemoController”. Frame the DemoController with the “ApiException” attribute to allow ApiFrame to handle the exception for you.

[ApiException]
publicclass DemoController : ApiController
{
}

Add the following methods to the DemoController. Let’s create the following methods for demo.

SignIn - POST method for Authentication demo

Relative route : /demo/signin

GetMessage - GET Method for Authorization demo

Relative route : /demo/getmessage

You will notice that the below SignIn method is framed with ApiAuthentication filter attribute. Similarly, GetMessage with ApiAuthorization filter attribute. This filter attributes handles the authentication and authorization by calling the injected methods implemented by IApiInception.

When calling the sign-in service, the server returns a token (Access token and secret token) on successful authentication. This token is preserved and used for subsequent service call. Below is the sample that call an authorized API service method that return a private message. Let’s the use the received token to make a next service call to get the private message

Hi John-ph,
Currently, I've just use the basic authentication with user/password that passing as parameter for every method call from html5.
Do you know how do I implement this scenario into html/js?
Thanks