Content Delivery API, EPiServer

Upgrade Episerver Content Delivery API 1.x site to use version 2.1.0

In this blog post I will show you how to upgrade an Episerver site using Content Delivery API 1.x version to use the just released version 2.1.0. I will use the Episerver Music Festival Vue.js template site as the sample as it is currently using Episerver Content Delivery API 1.0.1.

This post was edited 2018-12-06, I’ve changed the links to my fork to point to an orphaned branch as the Episerver musicfestival master has changed and I want to pull the latest to my master (and I had originally done changes to master).

Episerver Content Delivery API

If you are not familiar or if you are unaware of the Content Delivery API it is basically Episervers response for need to have support for headless CMS. An API that can deliver the same content used on the website to be consumed on SPA “pages”, on other sites, mobile apps and where ever you need the same content used on the traditional “coupled” site.

Look at the Episerver documentation about Content Delivery API.

Changes in Episerver Content Delivery API 2.1.0

The version 1.x was just one NuGet package that contained everything. In version 2.1.0 the single package is splitted to multiple NuGet packages so you as a developer can choose just the ones you need for your implementation. The packages and their purpose are explained in the documentation.

Here is a short recap of the packages:

  • install EPiServer.ContentDeliveryApi.Cms if you just need to be able to deliver content without authentication and search capabilities in the API
  • also install EPiServer.ContentDeliveryApi.OAuth if you need OAuth in the API
  • also install EPiServer.ContentDeliveryApi.Search if you need to support search capabilities in the API (Note! search requires Episerver Find search service)

At the end of the Content Delivery API installation instruction page there are few bullets about upgrading 1.x to 2.x but currently it doesn’t tell everything about the upgrade and changes that you might need to do. But more about the possible changes you might need to do follows in this post.

Episerver MusicFestival Vue.js Templates sample site

Episerver just made public the MusicFestival sample on GitHub. This is a sample site using Content Delivery API (1.0.1 currently) and Vue.js. If you haven’t read the blog posts about the MusicFestival Vue.js Templates then here are a few blog posts you should read:

Upgrading MusicFestival site to use Content Delivery API 2.1.0

To be able to share a real sample of upgrading Content Delivery API 1.x to 2.1.0 the Episerver MusicFestival sample is a perfect case as it is still using the version 1.0.1 of Content Delivery API.

MusicFestival sample doesn’t currently use all the possible features but most likely those are coming to the sample when time goes on.

So first I forked the MusicFestival sample to my GitHub account. My target was to just upgrade and make sure the site works the same way as it worked with the 1.0.1 version. The site includes readiness for all features and configuration for API search so that is the reason why I added all the features in the upgrade so the same readiness to use all features is still there.

After I had forked I just follwed the instructions how to setup MusicFestival and made couple of request to the Content Delivery API and saved the responses (so that I could later compare the results to the upgraded versions results). Next step was to update the EPiServer.ContentDeliveryApi NuGet package and add also add the EPiServer.ContentDeliveryApi.Search package (as it gets removed in the upgrade). After upgrade rebuilding the solution gives 18 errors. Time to fix the errors.

Upgrade errors

Biggest change affecting MusicFestival is that the IPropertyModelHandler has been replaced with IPropertyModelConverter interface (or should I say has been refactored). The refactored interface has also changes in the method and property signatures.

  • GetValue method is now ConvertPropertyModel
  • CanHandleProperty method is now HasPropertyModelAssociatedWith
  • ModelTypes property used to return List<TypeModel> but now returns IEnumerable<TypeModel>

This affects the BuyTicketBlockPropertyModelHandler implementation in MusicFestival sample.

Other changes include changes in namespaces, ContentApiHelper class has been moved to internal namespace EPiServer.ContentApi.Cms.Helpers.Internal and RouteConstants has also been moved to internal namespace EPiServer.ContentApi.Core.Internal.

How we configure Content Delivery API has also changed to use fluent API configuration. This affects the SiteInitialization code.

Fixing upgrade errors

So this part of the post will be a boring list of what was done but you can look this diff in GitHub to see all the changes in one go (and in a much clearer way vs what will follow in the below listing 😀 ).

  • src\MusicFestival.Vue.Template\Infrastructure\Owin\Startup.cs
    • remove: using EPiServer.ContentApi.Authorization;
    • remove: using EPiServer.ContentApi;
    • add: using EPiServer.ContentApi.Cms.Helpers.Internal;
    • add: using EPiServer.ContentApi.OAuth;
  • src\MusicFestival.Vue.Template\Infrastructure\SiteInitialization.cs
    • first remove all unused using clauses
    • add: using EPiServer.ContentApi.Core.Serialization;
    • add: using EPiServer.ContentApi.Core.Configuration;
    • add: using EPiServer.ContentApi.Search;
    • remove code that creates contentApiOptions and calls context.InitializeContentApi(contentApiOptions);
    • remove code that calls context.InitializeContentSearchApi
    • add new code that configures the content API and search
    • edit code: context.Services.AddTransient<IPropertyModelHandler, BuyTicketBlockPropertyModelHandler>();
      • replace IPropertyModelHandler with IPropertyModelConverter
    • after these change there are still two errors but we can ignore those for now
  • src\MusicFestival.Vue.Template\Infrastructure\BuyTicketBlockPropertyModel.cs
    • remove: using EPiServer.ContentApi.Core;
    • add: using EPiServer.ContentApi.Core.Serialization.Models;
  • src\MusicFestival.Vue.Template\Infrastructure\BuyTicketBlockPropertyModelHandler.cs
    • remove: using EPiServer.ContentApi.Core;
    • add: using EPiServer.ContentApi.Core.Serialization;
    • add: using EPiServer.ContentApi.Core.Serialization.Models;
    • replace IPropertyModelHandler with IPropertyModelConverter
    • rename method CanHandleProperty to HasPropertyModelAssociatedWith
    • rename method GetValue to ConvertToPropertyModel
    • change ModelTypes propertys type from List<TypeModel> to IEnumerable<TypeModel>
  • src\MusicFestival.Vue.Template\Models\ExtendedContentModelMapper.cs
    • remove: using EPiServer.ContentApi.Core;
    • add: using EPiServer.ContentApi.Core.Serialization;
    • add: using EPiServer.ContentApi.Core.Serialization.Models;
    • change PropertyModelHandlers property to return IEnumerable<IPropertyModelConverter>
  • src\MusicFestival.Vue.Template\Infrastructure\ContentDeliveryExtendedRouting\RoutingEventHandler.cs
    • RouteConstants.BaseContentApiRoute is in new namespace (internal)
    • so change: EPiServer.ContentApi.RouteConstants.BaseContentApiRoute to EPiServer.ContentApi.Core.Internal.RouteConstants.BaseContentApiRoute

There is also change in the code so that it will call MapHttpAttributeRoutes() and the MusicFestival code has already called this method. This would cause an error when the site start up so you need to disable the Content Delivery API and Search calling this method again. This is documented in Content Delivery API configuration instructions.

  • modify web.config and add the following to appSettings
    • <add key=”episerver:contentdeliverysearch:maphttpattributeroutes” value=”false” />
    • <add key=”episerver:contentdelivery:maphttpattributeroutes” value=”false” />

I also later noticed that MusicFestival sample was having the old signed structuremap NuGet packages so I also removed those in a separate commit. Basically you first need to remove the package EPiServer.ServiceLocation.StructureMap and then remove packages structuremap.web-signed and structuremap-signed (if they are left). Remove StructureMap from web.config assemblyBinding if it is there. Then install EPiServer.ServiceLocation.StructureMap 2.0.0 (or later version) back (it should also bring the structuremap and structuremap.web packages back).

Closing words

So the actual upgrade was quite easy and only few changes needed to be done to the custom code. Amount of changes needed to be done really depends on your solution if you have heavily used the IPropertyModelHandler interface which has changed to IPropertyModelConverter but as you know now what needs to be done – “it’s monkey coding to make your solution work” (what I mean is that a trained monkey can do the replacing :D).

Quickly testing the API after the upgrade and comparing the returned results — looks like it still works the same.

As a closing note, this was just my take on this and making assumptions that this is how the upgrade should be done in the simplest case. I take no responsibility if you use this code and blow up your implementation 😀


3 thoughts on “Upgrade Episerver Content Delivery API 1.x site to use version 2.1.0

      1. FYI: The PR was rejected because Episerver will make also other modifications to the MusicFestival sample site. So follow the repo or Episerver blog postings to get notified when the sample gets updated.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s