Contensis R8.2 adds a number of features that developers and designers will love. One of these features is the adoption of ApiControllers.
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)
The use of ApiControllers will feature more and more in future releases of Contensis, and enables many more opportunities to extend the power of Contensis powered websites.
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
In R8.2 we have shipped a Contensis specific ApiController - imaginatively named ContensisApiController. 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.
In future releases, we would envisage that ContensisApiController would be further extended as we introduce more features, so we would advise that any developer wanting to develop extensions on their website that will or may utilise features of Contensis - that your ApiControllers inherit from ContensisApiController.
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
As stated earlier, the Contensis Forms module has further been extended in R8.2 - with a focus on allowing 3rd party integrations. To complement this improvement, R8.2 also ships with 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.
Hopefully this has given you enough information to whet your appetite to integrate your website with your other line of business applications, and with the use of ApiControllers, Contensis Forms improvements as well as the ContensisForm helpers you have all the integration tools you need in your toolbox.