Using CRM from an external website – part 4: Demo “Web API”

Originally posted on 25 August 2015 by Bas van de Sande on JourneyIntoCRM.com

Welcome to the next episode in the “Using CRM from an external website” series. In my last article, I described the Web API scenario. The Web API scenario is the first step in the journey and depends on Microsoft Infrasctrucure ( I need a .Net/Mono framework and an Internet Information like server).

In this scenario I hook up a web page to a Web API controller. The model behind the controller is responsible for getting the data from the back end CRM. As the Web API controller and the model are running in a .NET context, we simply can use the Dynamics CRM object model to get and set the data from CRM.

I Use javascript on the web page to make the REST calls. For data retrieval (Select and SelectList) I use a GET method. For Data manipulation (Insert, Update, Delete) I use a POST method. The javascript conducting the calls to the Web API controller are the bridge between the client side context and the server side context.

Webapi

In this article I’ll show you the main concepts on passing data from the client side context to the server side context and vice versa. For the sake of simplicity the model class is not conducting any operation towards CRM.

MVC

The Web API scenario is based on the MVC principles. We work with a single controller or multiple controllers (to define the actions) and with a model or multiple models (containing the data).
Using MVC we need to specify where our controllers can be found. This has to be done in a RouteTable.  In the RouteTable you can specify how your URL’s should look like.

The RouteTable is specified in the global.asax file in the web project.

Webapiglobalasax

Model

The basis of the Web API scenario is the model. In the model we define how the data should look like. In my implementation I use the model in a fashion that I can pass the model outside the boundaries of the assembly and still keeping full control over the behaviour of the class. I specified public properties and internal methods.

The public properties can be get and set by anyone. The internal methods can only be called within the context of the assembly (read: controller).

The idea of using a model is to simplify the transport of data over the server side and client side context.

Webapimodel

Controller

The controller acts like a façade (gateway) between the client side and server side context. As you can see all functions are decorated with two attributes.

  • HttpPost / HttpGet
    This attribute defines in what context the function is called. By either a HttpGet or a HttpPost method.
  • ActionName
    This attribute defines the name of the function to the outside world. This way we can give meaningfull names to our get and post methods and we can have multiple get and post methods within the controller.

To simplify communication between the server side and client side context, we try to work as much as possible with simple data types (like string etc), instead of using complex objects. However, when you look at e.g. the Insert() function, you see that we pass in a string representing a model.
The model is deserialized and instantiated into our strong typed model class.

Once instantiated we can call the appropriate method on the model to conduct the action we desire. On the other hand we can return complex objects back to the client side context by simply using the object.  The javascript JSON call handles all serialization and deserialization for us. *nifty*

Webapicontroller

Javascript methods

On the web page we have basically two kinds of methods. Either a GET or a POST method.

Looking at the GET method, we simply specify the URL in the format defined in the RouteTable. We have to omit the word “Controller”, that is handled by MVC.

Our url looks like:

“api / [name of the model] / [method on the controller] / ?[parameter]”.

Please note that method names and parameters are case sensitive. Once the data is retrieved, we simply can use the properties defined in the model (case sensitive)

Webapi-get

Looking at the POST method, we have to a a bit more work.
First of all we have to fill a JSON object and stringify it (encode it for transport).
Then we pass it to our url in a parameter. Our url is enriched with a string representing our model. In the controller we deserialize the string and turn it into a .NET object.

Webapi-post

This is in a nutshell all technology you need to integrate your CRM environment in your website. As I mentioned before, this is only the first step. In this example I trust on the security mechanisms offered by the .NET framework and the Microsoft infrastructure. My ultimate goal is to be able to integrate my CRM environment with a non Microsoft environment.

Filed under: Blog