Arlo .Net API client - Demo website code

The demo project with source (attached ZIP at bottom of this document) is an ASP.NET website that is composed of a number of pages representing a basic website promoting courses/events, presenters and venues.

Each page typically has one or more UserControls (or modules) which provide relatively isolated sections of information such as lists or course content.

For example, the page for an event (Event.aspx) has a module at the top of the page for the summary text, and several more modules below it for each section of content such as Description and Prerequisites. Other pages, such as the Events.aspx page has a single module comprising the main gallery/list of courses on the page.

To run the demo, extract the ZIP open the .csproj file in Visual Studio 2012 and hit F5/Run to start it. This should launch the VS web server on port 57000 and open a browser to http://localhost:57000/Default.aspx. The project will pull data from our live API endpoint over the web.

If for any reason that doesn’t work, you can create a new (local) IIS website and point the site at the root of the project with a binding of *:57000.

In the project is a Web.config file that will (by default) point at the API service of a demo build (which can also be configured in the top right of the app).

Server: api.learningsourceapp.com

Platform: demo-au

The website will point at the ‘demo-au’ platform which is live in production.

Important: The API will return links to courses and categories with URLs starting with http://demo.learningsource.com.au which will take you to the external hosted pages for these in production. This means if you click course or category links in the local app page you’ll probably be taken to the external platform site. This isn’t a problem with the API but is rather an issue of configuration as this particular demo platform isn’t specifically configured for API use which means it doesn’t modify the URLs it returns.

• Catalogue page http://localhost:57000/Catalogue.aspx (course links will be to live site)
• Calendar page http://localhost:57000/EventsCalendar.aspx (register links will be to live site)
• Presenters list page http://localhost:57000/Presenters.aspx (presenter links will be to live site)
• Venues list page http://localhost:57000/Venues.aspx (venue links will be to live site)
• Course/event search page http://localhost:57000/Search.aspx
• Individual event page: http://localhost:57000/Event.aspx?id=9088
• Individual presenter page http://localhost:57000/Presenter.aspx?id=10555
• Individual venue page http://localhost:57000/Venue.aspx?id=9026 

Each module has its own CSS, and sometimes some script. Note that the layout/CSS is for demo purposes only – it isn’t production ready and has no real support for IE8 or below. The point of the CSS is to allow practical interaction with the demo as opposed to being some constraint or guide on how the API or its UserControls need to be laid out.

API calls are high latency (response time likely measured in hundreds of milliseconds) which is largely due to round trip time (as opposed to server processing time). Whereever possible, code should avoid calling the API, and where calls are necessary they should be used as sparingly as possible – one or two calls for a whole page, rather than retrieving a list, looping over it and then making additional calls for each loop element.

We’ve worked hard to ensure that most (if not all) of the API endpoints retrieve entire page datasets with typically three or fewer API calls.

To mitigate the high latency of the API, the .NET client for ASP.NET has a built in cache which uses the HttpApplication memory cache to store responses. The length of store and revalidation frequency is controlled by the API server which includes cache directives in its responses. In the current build, the typical cache directive is for 15-30 minutes with asynchronous revalidation after that period.

To also help with performance, the API client uses gzip compression when communicating with the API server which substantially reduces the volume of traffic that needs to be transferred for each server response. 

In the demo project, there are a number of performance features to ensure pages are as fast as they can be:  

1. Virtually all usage of the API client is via the Async methods which immediately return Task<T> instances and don’t wait for the server to respond. The synchronous versions of the same API calls (which block and return the result from the server in the same method call) are not recommended for server code.
2. All of the UserControls are asynchronous and execute the majority of their work for a single page request in threads, in parallel. The built in PageAsyncTask architecture of ASP.NET is used for this. The total execution time for the page will be dictated by the API call that takes the longest.
3. Key pages (in addition to their UserControls) are also asynchronous with largely non-linear execution strategies. These pages start work (Tasks) in their OnInit handlers and expect the results to be ready by the PreRenderComplete page lifecycle event. 

For example, the Event page needs the title of the event so it can fill in the header at the top of the page. The API call to retrieve this information is started in OnInit and the page doesn’t actually need the result of this call until very late in the render lifecycle. See Event.aspx.cs, Venue.aspx.cs and Presenter.aspx.cs for more information on how these pages manages asynchronous execution. 

Without aspects (2) and (3) the execution of the pages will be measured in seconds (instead of milliseconds) as each UserControl will block the page execution until its API calls complete. 

The Client exists in three assemblies:

• LS.ApiClient.dll – the core of the client, independent of ASP.NET or any web framework.
• LS.ApiClient.AspNet.dll – extends the client to use ASP.NET HttpContext and HttpApplication cache.
• LS.ApiClient.log4net.dll – provides access to internal trace events via log4net Appenders. We may write implementations which support other logging frameworks. This assembly can be dropped if you don’t want to use log4net.

Inside ASP.NET applications, the recommended way of obtaining an IPublicRestApiClient instance is by using code like:

//Get API client for this request

IPublicRestApiClient apiClient = HttpContextApiClientManager.Current.GetApiClient();

if (apiClient == null) {

    throw new ApplicationException(string.Format("Unable to obtain {0} instance", typeof(IPublicRestApiClient).FullName));

}

As its name suggests, the HttpContextApiClientManager is used only within the context of an HTTP request. It will return an API client initialized with settings from your web.config and configured with support for the HttpApplication memory cache. You can find example uses of the client throughout the ASPX pages and ASCX user controls.

Outside of HTTP requests, such as in a background thread that runs between requests, you will not be able to use the HttpContextApiClientManager. Instead you will need to use code like:

IPublicRestApiClient apiClient = new PublicRestApiClient(

    "MyPlatformID",

    new PublicRestApiClientConfig() {

        ApiBaseUri = new Uri("https://api.learningsourceapp.com")

    }

);