Designing a Mobile-Enabling API

What does it look like to use the Services Framework?

Technology Overview

• Based on ASP.NET Web API
• Register routes to direct requests to controller actions
• Implement controllers to process requests
• Try to let the framework handle serialization into JSON or XML

Routes

• Implement IServiceRouteMapper interface
  • void RegisterRoutes(IMapRoute)
• Call MapHttpRoute method on IMapRoute argument
• Services route to /DesktopModules/Module/API/[route]
• Define placeholders or defaults for the controller
• By default, the action is determined by the HTTP verb

        /*GET /DesktopModules/Example/S/API/Example.ashx*/
        namespace Example.Dnn.Services {
            using DotNetNuke.Web.Api;

            public class Mapperator : IServiceRouteMapper {
                public void RegisterRoutes(IMapRoute mapper) {
                    mapper.MapHttpRoute(
                        moduleFolderName: "Example/S", 
                        routeName: "default",
                        url: "{controller}.ashx", 
                        namespaces: new[] { 
                            "Example.Dnn.Services",
                        });
                }
            }
        }
        

Controllers

• Inherit from DnnApiController
• Class name must end with Controller
• All public methods are actions
• Actions typically return HttpResponseMessage

        namespace Example.Dnn.Services {
            using System.Net;
            using System.Net.Http;
            using DotNetNuke.Web.Api;

            public class ExampleController : DnnApiController {
                public HttpResponseMessage GetHello() {
                    return this.Request.CreateResponse(
                        HttpStatusCode.OK, 
                        new { 
                            number = 1, 
                            text = "Hi!",
                    });
                }
            }
        }
        

Authorization

• Only host-level access by default
  • Different than Web API defaults
• AllowAnonymousAttribute
  • Disables all authorization
  • Only use on actions, never at controller level
• DnnAuthorizeAttribute
  • Static list of role names
• RequireHostAttribute
  • Override looser authentication from controller

Authentication

• Forms authentication cookie (AJAX)
• Basic access authentication
  • Requires HTTPS/SSL for security
  • Passes credentials on each request
• Digest access authentication
  • Uses MD5 for "security"
  • Passes credentials on each request
• Need an OAuth (or other token-passing) solution
• Anti-Forgery Token

DNN Context

• UserInfo (and authentication)
• ActiveModule
• PortalSettings
  • ActiveTab
  • HomeDirectoryMapPath
  • AdministratorId
  • AdministratorRoleName
  • CultureCode
  • PortalAlias
  • etc.

        using DotNetNuke.Framework;

        public class MyModuleControl : ModuleView<MyViewModel> {
            protected MyModuleControl() {
                ServicesFramework.Instance.RequestAjaxAntiForgerySupport();
            }
        }
        

        var sf = $.ServicesFramework(<%:ModuleContext.ModuleId%>);
        $.ajax({
            type: 'GET',
            url: sf.getServiceRoot('Example/S') + 'Example.ashx',
            beforeSend: sf.setModuleHeaders,
            data: {}
        }).done(function (data) { /*...*/ })
          .fail(function (xhr, status) { /*...*/ });
        

            var requestUri = new Uri("http://dnn7.dev/DesktopModules/Example/S/API/Example.ashx");
            var request = new HttpRequestMessage(HttpMethod.Get, requestUri);
            request.Headers.Add("ModuleId", "1740");
            request.Headers.Add("TabId", "56");

            var client = new HttpClient(new HttpClientHandler { 
                Credentials = new NetworkCredential("host", "pa$$") 
            });
            var response = await client.SendAsync(request);
            if (!response.IsSuccessStatusCode) {
                // TODO: show error
                return;
            }

            var json = await response.Content.ReadAsStringAsync();
        

Wrap Up

• Implementation
• Benefits
• Usage

More Info

• http://bit.ly/DNN-Services
• http://bit.ly/DNN-Services-Pres

Thanks to all our Generous Sponsors!