Microsoft .Net WebForm applications are typically made up of web pages (.aspx). These pages can be written using a combination of HTML, client-script, server controls, and server code. When users request a page, it is compiled and executed on the server by the framework, and then the framework generates the HTML markup that the browser can render. An ASP.NET Web Forms page presents information to the user in any browser or client device.
More recently, there has been a shift towards .NET MVC whereby there is a more distinct separation between the UI (Views), data (Model) and the HTTP request handler (Controller). This UI pattern gives a clear separation of concerns - and a clear benefit of increased testability - among many other improvements.
ApiControllers are really just an extension of a typical MVC Controller. HTTP is not just for serving up web pages. It is also a platform for building APIs that expose services and data. HTTP is simple, flexible, and cross platform. Almost any platform that you can think of has an HTTP library, so HTTP services can reach a broad range of clients, including browsers, mobile devices, and traditional desktop applications.
How we are making use of ApiControllers
- Handle custom HTTP end-points for the Contensis Forms module - enabling integration with 3rd party applications (CRMs, Payments gateways etc).
- The ContensisForm Helpers in Razor views use them to handle form posts and redirects.
- Contensis webhooks can easily use them in your front end websites enabling a 2 way integration between Contensis and 3rd party applications (e.g. synchronise user data with a CRM)
Attribute based routing
Part of the feature set of WebApi 2 (aside from the confusing versioning!), is the introduction of Attribute Based Routing. By utilising Attribute Based Routing in your ApiController, you have complete control over the Api structure that you expose on your website. Its easy to configure and has very few limitations on what can be achieved by using it.
Working with WebAPI 2 in Contensis is just the same as if you were to use it within your own WebApi applications. To find out more, just read up on attribute based routing at the official Asp.net website.
In order to deploy ApiControllers to your website, we recommend that you make use of the App_Code folder within your website. This is a special folder called “App_Code” that should exist in the root of your website. You can read all about the App_Code folder over at MSDN, or check out our article on App_Code which focuses on its use within Contensis.
Contensis specific ApiController
This class can be found in the Contensis.Framework.Web namespace which is referenced as default in a Contensis website.
The ContensisApiController is a very lightweight abstract ApiController that currently gives you access to the current Contensis user as well as providing some convenience methods for returning values to both the Contensis Forms module as well as the ContensisForm Helper for Razor views.
The overloaded methods are important for use with both the Forms Module and the ContensisForm Helpers. Some examples of the CreateResponse and CreateErrorResponse can be seen in the following code block.
Returning simple message
To return a message to the ContensisForm which would display within a ContensisFormSummary simply:
Returning a redirect
To mimic a traditional form, and actually redirect a user to a different Url, perhaps a confirmation page or different website altogether, use the following overloaded method:
If you want to return an exception to the ContensisForm use the CreateErrorResponse method:
Contensis forms module ApiController
The extended Contensis Forms module has a focus on allowing 3rd party integrations. and has an ApiController specifically to help developers achieve this. The ContensisFormsApiController is the ApiController to inherit for this purpose. It builds on the ContensisApiController to reduce the amount of work our clients need to do to perform common tasks.
The ContensisFormsApiController performs additional features such as:
- Presenting the forms name value collection in a friendly manner
- Automatically creates the form post within Contensis - so you get the best of both worlds
- Allows you to prevent the creation of form posts - to assist with testing
- Gives the ability to update the form post - useful for updating a form post with a CRM reference number or payment transaction ID.
As the ContensisFormsApiController requires its sub-classes to override an abstract method, it uses convention based routing instead of attribute based routing. This means that you cannot specify the route itself. Any ApiController that inherits from the ContensisFormsApiController can be accessed using the following convention
There are some examples of Contensis Forms integrations on the marketplace (including Microsoft Dynamics CRM, SalesForce CRM and PayPal). Make sure you check them out and extend them to fit your exact business need.