Serialization

📘

Note

This section applies only if you are still using Content Delivery Api v2.x.x. It does not apply to customers using version 3.

What is serialization?

The Content Delivery API takes your content in the Optimizely database and converts it into JSON format, which is a format that encodes objects in a string. This conversion of objects into a string is called serialization. The opposite conversion, from string to object, is called deserialization.

Serialization converts complex objects into byte strings which can be transmitted. After the transmission, the recipient has to deserialize the byte strings to recover the original object.

📘

Example

If you have the object {foo: [1, 4, 7, 10], bar: "epi"}, serializing this into JSON converts it into the string '{"foo":[1,4,7,10],"bar":"epi"}' . The recipient can then deserialize this string into the original object {foo: [1, 4, 7, 10], bar: "epi"}.

How it works

The Content Delivery API defines two concepts, ContentApiModel and PropertyModel, which play a role as data transform objects for the serialization process. Basically, data is transformed to those models before being returned as the request result. The main serialization flow is illustrated by the diagram below.

The workflow should be as follows:

1. You make a request to an endpoint to query data.
2. The request is handled by components (filter, controllers, services, etc) and assumes that the expected data is retrieved in forms of IContent, IEnumerable, or Errors.

IContent instances are transformed to ContentApiModel, so this is basically a copy of the Content populated with whatever content interfaces your content implements.

• The properties of IContent are migrated to ContentApiModel.
• The PropertyDataCollection of IContent is converted to a list of PropertyModel and then migrated to ContentApiModel.
• ContentApiModel is wrapped in ContentApiResult. Then, the serializer of ContentDeliveryApi serializes everything into JSON and returns it.

This table maps properties between ContentData and ContentApiModel:

Example - Serialization, Alloy template

You can use the Alloy template to see the default configuration with predefined endpoints and output models.

ProductPage class

This is the code for the Alloy ProductPage:

namespace EpiAlloy.Models.Pages
{
    /// <summary>
    /// Used to present a single product
    /// </summary>
    [SiteContentType(
        GUID = "17583DCD-3C11-49DD-A66D-0DEF0DD601FC",
        GroupName = Global.GroupNames.Products)]
    [SiteImageUrl(Global.StaticGraphicsFolderPath + "page-type-thumbnail-product.png")]
    [AvailableContentTypes(
        Availability = Availability.Specific,
        IncludeOn = new[] { typeof(StartPage) })]
    public class ProductPage : StandardPage, IHasRelatedContent
    {
        [Required]
        [Display(Order = 305)]
        [UIHint(Global.SiteUIHints.StringsCollection)]
        [CultureSpecific]
        public virtual IList<string> UniqueSellingPoints { get; set; }

        [Display(
            GroupName = SystemTabNames.Content,
            Order = 330)]
        [CultureSpecific]
        [AllowedTypes(new[] { typeof(IContentData) },new[] { typeof(JumbotronBlock) })]
        public virtual ContentArea RelatedContentArea { get; set; }
    }
}

If you retrieve a product page through the Content Delivery API, you will get the following result:

JSON output from Alloy product page

{
	"contentLink": {
		"id": 6,
		"workId": 0,
		"guidValue": "567a6012-5af2-4f26-a198-593326b80722",
		"providerName": null,
		"url": "/en/alloy-plan/"
	},
	"name": "Alloy Plan",
	"language": {
		"link": "/en/alloy-plan/",
		"displayName": "English",
		"name": "en"
	},
	"existingLanguages": [
		{
			"link": "/en/alloy-plan/",
			"displayName": "English",
			"name": "en"
		}
	],
	"masterLanguage": {
		"link": "/en/alloy-plan/",
		"displayName": "English",
		"name": "en"
	},
	"contentType": [
		"Page",
		"ProductPage"
	],
	"parentLink": {
		"id": 5,
		"workId": 0,
		"guidValue": "0b9c1a6e-129a-456b-ac3c-5a1b108362e0",
		"providerName": null,
		"url": "/en/"
	},
	"routeSegment": "alloy-plan",
	"url": "/en/alloy-plan/",
	"changed": "2019-10-28T14:26:13Z",
	"created": "2012-08-22T15:15:48Z",
	"startPublish": "2012-08-22T15:15:48Z",
	"stopPublish": null,
	"saved": "2019-10-28T14:26:13Z",
	"status": "Published",
	"category": {
		"value": [
			{
				"id": 3,
				"name": "Plan",
				"description": "Alloy Plan"
			}
		],
		"propertyDataType": "PropertyCategory"
	},
	"metaTitle": {
		"value": "Alloy Plan, online project management",
		"propertyDataType": "PropertyLongString"
	},
	"pageImage": {
		"value": {
			"id": 43,
			"workId": 0,
			"guidValue": "c04c11c5-4314-4fdc-b1b8-c3bfb9fdb9d8",
			"providerName": null,
			"url": null
		},
		"propertyDataType": "PropertyContentReference"
	},
	"teaserText": {
		"value": "Project management has never been easier!",
		"propertyDataType": "PropertyLongString"
	},
	"hideSiteHeader": {
		"value": null,
		"propertyDataType": "PropertyBoolean"
	},
	"metaDescription": {
		"value": "Project management has never been easier! Use Alloy Meet with Alloy Plan to get the whole team involved in the creation of project plans and see how this commitment translates into finite and achievable goals.",
		"propertyDataType": "PropertyLongString"
	},
	"hideSiteFooter": {
		"value": null,
		"propertyDataType": "PropertyBoolean"
	},
	"uniqueSellingPoints": {
		"value": [
			"Project planning",
			"Reporting and statistics",
			"Email handling of tasks",
			"Risk calculations",
			"Direct communication to members"
		],
		"propertyDataType": "PropertyStringList"
	},
	"mainBody": {
		"value": "<p><img style=\"float: left;\" src=\"/contentassets/89bccbae16d14665b08fac3525c9a999/alloyplanscreen.png\" alt=\"Alloy Plan - Efficient project planning\" /></p>\n<p>Planning is crucial to the success of any project. Alloy Plan takes into consideration all aspects of project planning; from well-defined objectives to staffing, capital investments and management support. Nothing is left to chance.</p>\n<p>Alloy Plan supports all project methodologies efficiently as the system is totally flexible in terms of setup and use.</p>\n<p>Realize the benefits of using Alloy Plan. Our customers see on average  an 80% increase in delivery of their projects on time, on budget and  with minimal risk involved.</p>\n<p>Work with an Alloy Technology partner to define the scale of your organization's needs and find the best fit with Alloy Plan.</p>",
		"propertyDataType": "PropertyXhtmlString"
	},
	"mainContentArea": {
		"value": [
			{
				"displayOption": "wide",
				"tag": null,
				"contentLink": {
					"id": 46,
					"workId": 0,
					"guidValue": "7026878a-a6e3-4916-811d-40bf3fd9b50b",
					"providerName": null,
					"url": null
				}
			},
			{
				"displayOption": "narrow",
				"tag": null,
				"contentLink": {
					"id": 28,
					"workId": 0,
					"guidValue": "2e90d62d-4abe-4c75-b87e-27817edad095",
					"providerName": null,
					"url": null
				}
			},
			{
				"displayOption": "narrow",
				"tag": null,
				"contentLink": {
					"id": 31,
					"workId": 0,
					"guidValue": "da738746-4912-4603-953c-d727f744fa91",
					"providerName": null,
					"url": null
				}
			}
		],
		"propertyDataType": "PropertyContentArea"
	},
	"relatedContentArea": {
		"value": [
			{
				"displayOption": "",
				"tag": null,
				"contentLink": {
					"id": 47,
					"workId": 0,
					"guidValue": "2dfadba3-31f8-45ac-9d80-6c8ff3a51b5e",
					"providerName": null,
					"url": null
				}
			},
			{
				"displayOption": "",
				"tag": null,
				"contentLink": {
					"id": 48,
					"workId": 0,
					"guidValue": "87d2fa31-712a-4dac-b57c-a369d28f149b",
					"providerName": null,
					"url": null
				}
			}
		],
		"propertyDataType": "PropertyContentArea"
	},
	"disableIndexing": {
		"value": null,
		"propertyDataType": "PropertyBoolean"
	}
}

As you can see, you get a lot of data with the default configuration. However, all this data, such as masterLanguage, changed, created, startPublish, stopPublish, might not be necessary for your front-end site. Other pieces might be necessary but in another format; contentLink and parentLink should perhaps be included but as integer IDs, and perhaps you would like enum rendered as a string name and not as a number, and URLs to be relative and not absolute. This is where some customization of the serialization needs to be done.

Customize the serialization

If the standard JSON output does not suit your needs, you can customize the serialization to get a different output. You can customize the serialization in a number of ways:

• Using the JsonIgnore attribute
• Property Model mappers
• Customize the IContentModelMapper implementation
• Filter the output model
• Create custom controller

JsonIgnore attribute

If you have ContentData properties that you do not want to be included in the JSON output, just decorate it with the JsonIgnore attribute and it is ignored in the resulting model. The attribute is checked by the ContentModelMapperBase during ContentApiModel building and ignores it if it is present.

[JsonIgnore]
	[Display(
		GroupName = SystemTabNames.Content,
		Order = 330)]
	[CultureSpecific]
	[AllowedTypes(new[] { typeof(IContentData) },new[] { typeof(JumbotronBlock) })]
	public virtual ContentArea RelatedContentArea { get; set; }

Property Model mappers

The Property model is the Content Delivery version of PropertyData, so this is the JSON that is rendered for your content properties.

For example, the PropertyNumber is represented by NumberPropertyModel. The NumberPropertyModel has a Value (the numeric value of property) and a PropertyDataType which usually is the name of the value type (in this case PropertyNumber).

/// <summary>
/// Mapped property model for <see cref="PropertyNumber"/>
/// </summary>
public class NumberPropertyModel : PropertyModel<int?, PropertyNumber>
  {
    public NumberPropertyModel(PropertyNumber propertyNumber) : base(propertyNumber)
      {
        Value = propertyNumber.Number;
      }
  }

These are the base classes/interfaces for model serialization.

You can use these base classes to implement and register your own custom property models and that way change how custom property types from PageData are serialized. See Custom property models for more information.

IPropertyModel

This is the most basic Interface that needs to be implemented according to the default PropertyModelConverter (see below). It only contains two properties:

PropertyModel<TValue,TType>

The IPropertyModel interface also needs a constructor with a parameter with the PropertyData. For convenience, the Content Delivery API has a base class for this, that is EPiServer.ContentApi.Core.Serialization.Models.PropertyModel\<TValue,TType>, where TValue is the value should be ouputed in JSON and TType is the type of PropertyData.

As the PropertyModel is serialized to JSON, all properties on the implementation are included in the result. The only exception is if you have decorated a property with the JsonIgnore attribute.

IPersonalizableProperty

If the output of the property depends on personalization, implement the IPersonalizableProperty. The interface only requires a Property called ExcludePersonalizedContent which used to determine if personalized content should be excluded when retrieving content.

public class MyPersonalizedPropertyModel : IPropertyModel, IPersonizableProperty
{
    public MyPersonalizedPropertyModel(MyPropertyData property, bool excludePersonalizedContent)
    {
        if (excludePersonalizedContent)
        {
            // add logic to exclude personalized content
        }
    }

    public string Name { get; set; }
    public string PropertyDataType { get; set; }
    public bool ExcludePersonalizedContent { get; set; }
}

By default, property models of ContentArea, ContentReference, ContentReferenceList, and LinkCollection implement this interface. Content Delivery API also has a base class that is EPiServer.ContentApi.Core.Serialization.Models.PersonalizablePropertyModel\<TValue, TType> where TValue is the value that should be outputted in your JSON, and TType is the type of PropertyData.

IExpandableProperty

This interface is used for properties where you can return a simplified set of data for the initial API Request, so that the server can make further requests to the database to dig deeper into the data. By default, the following property types can be expanded: ContentArea, ContentReference, ContentReferenceList, and LinkCollection.

Expand it by adding the parameter ?expand=Steps or ?expand=\*. Note that expanding a property only works on the first level of nested content; it does not work on lower levels.

Code example: Response without expanded parameter

"MyContentArea": {
    "Value": [
        {
            "ContentLink": {
                "Id": 9,
                "WorkId": 0,
                "GuidValue": "5f3d81e6-28f8-4f16-b998-87378fc9c4d6",
                "ProviderName": null
            },
            "DisplayOption": "",
            "Tag": null
        }
    ],
    "PropertyDataType": "PropertyContentArea"
}

Code example: Response with expanded parameter

"MyContentArea": {
    "ExpandedValue": [ // When expanding, expanded information goes here
        {
            "ContentLink": {
                "Id": 9,
                "WorkId": 0,
                "GuidValue": "5f3d81e6-28f8-4f16-b998-87378fc9c4d6",
                "ProviderName": null
            },
            "Name": "My Block",
            "Language": {
                "DisplayName": "English",
                "Name": "en"
            },
            "ExistingLanguages": [
                {
                    "DisplayName": "English",
                    "Name": "en"
                }
            ],
            "MasterLanguage": {
                "DisplayName": "English",
                "Name": "en"
            },
            "ContentType": [
                "Block",
                "MyBlock"
            ],
            "ParentLink": {
                "Id": 8,
                "WorkId": 0,
                "GuidValue": "87a9ae8a-a2a8-40e5-8c09-5c5c55a73e17",
                "ProviderName": null
            },
            "RouteSegment": null,
            "Url": null,
            "Changed": "2018-04-09T16:05:01Z",
            "Created": "2018-04-09T16:05:01Z",
            "StartPublish": "2018-04-09T16:05:01Z",
            "StopPublish": null,
            "Saved": "2018-04-09T16:05:34Z",
            "Status": "Published",
            "Category": {
                "Value": [],
                "PropertyDataType": "PropertyCategory"
            },
            // Other properties goes here
        }
    ],
    "Value": [ // Here goes the original value before expanding
        {
            "ContentLink": {
                "Id": 9,
                "WorkId": 0,
                "GuidValue": "5f3d81e6-28f8-4f16-b998-87378fc9c4d6",
                "ProviderName": null
            },
            "DisplayOption": "",
            "Tag": null
        }
    ],
    "PropertyDataType": "PropertyContentArea"
}

IPropertyModelConverter

This interface is responsible for mapping data between PropertyData and PropertyModel. The default implementation DefaultPropertyModelConverter uses reflection to automatically map PropertyData with the corresponding PropertyModel.

Custom property models

If you do not want to use the built-in property models, you can implement and register custom property models. These can change how a property type is serialized and they apply to custom property types of the page data. The custom property models do not affect the internal IContent object properties or the visibility of the property.

To create a custom property model, create a class that inherits from EPiServer.ContentApi.Core.Serialization.Models.PropertyModel and set the Value property in your constructor. It is possible to map your property type to any class, as long as it is serializable and can be properly indexed into Optimizely Search & Navigation (formerly Optimizely Find).

Example: Forcing PropertyLongString to lowercase

The following custom property model forces all PropertyLongString instances to lowercase.

public class LowercaseLongStringPropertyModel : PropertyModel<string, PropertyLongString>
  {
    public LowercaseLongStringPropertyModel(PropertyLongString propertyLongString) : base(propertyLongString)
      {
        if (propertyLongString != null)
          {
            Value = propertyLongString.ToString().ToLower();
          }
      }
  }

Example: Changing Boolean value to integer

This example changes the rendering of Boolean values null, true, false to integers -1, 1, 0:

public class CustomBooleanPropertyModel : PropertyModel<int, PropertyBoolean>
    {
        public CustomBooleanPropertyModel(PropertyBoolean propertyBoolean)
            : base(propertyBoolean)
        {
            this.Value = propertyBoolean.Boolean.HasValue ? Convert.ToInt32(propertyBoolean.Boolean.Value) : -1;
        }
    }

Example: Include local blocks in JSON (for versions 2.6.1 and lower)

In versions prior to 2.9, local blocks were not included by default in the JSON output. To include those, you had to create a custom property model and put PropertyBlock as TType.

1. Create a custom block. Music Festival code example.
2. Create property model for custom block. Music Festival code example.
3. Create property model converter. Music Festival code example.
4. Display its value on the user interface. Music Festival code example.

Along with EPiServer.ContentApi.Core.Serialization.Models.PropertyModel, custom property models can also inherit from EPiServer.ContentApi.Core.Serialization.Models.PersonalizablePropertyModel. This class is used when custom property models contain data that is dependent on personalization. It adds an additional constructor parameter, excludePersonalizedContent, which allows you to implement logic in your property model to set the Value property differently in personalized vs. non-personalized contexts.

Register custom property models

For your custom property models to take effect, you need to create a custom implementation of IPropertyModelConverter. The implementation of IPropertyModelConverter has a collection of EPiServer.ContentApi.Core.Serialization.Models.TypeModel called ModelTypes, which maintains a map of which PropertyData instances that the converter is capable of handling.

The simplest method of adding a custom converter is to extend the default one, DefaultPropertyModelConverter, and override the SortOrder and ModelTypes properties.

Example: The following handler registers the LowercaseLongStringPropertyModel from the above example, with a SortOrder higher than the default handler (SortOrder = 0), ensuring that the custom converter is used for all Long String properties.

[ServiceConfiguration(typeof(IPropertyModelConverter), Lifecycle = ServiceInstanceScope.Singleton)]
public class LowercaseLongStringPropertyModelConverter : DefaultPropertyModelConverter
  {
    public LowercaseLongStringPropertyModelConverter()
      {
        ModelTypes = new List<TypeModel>
          {
            new TypeModel 
              {
                ModelType = typeof(LowercaseLongStringPropertyModel), ModelTypeString = nameof(LowercaseLongStringPropertyModel), PropertyType = typeof(PropertyLongString)
              }
          };
      }
    public override int SortOrder { get; } = 100;
  }

In some cases, a full implementation of IPropertyModelConverter may be preferable, such as when custom logic is required to choose between different PropertyModel implementations. In that case, your custom converter must also implement HasPropertyModelAssociatedWith, which verifies, based on the provided PropertyData, that the implementation of IPropertyModelConverter is able to handle the provided type. In addition, your custom converter must also implement ConvertToPropertyModel method, which creates and returns any instances of your custom property models based on the provided instance of PropertyData.

Work with ContentModelMapper

The IContentModelMapper implementation is where you can customize built-in PageData properties. It gives you full control over ContentApiModel and its properties are converted and mapped. Derive from DefaultContentModelMapper and then override one or more virtual methods of ContentModelMapperBase.

Note that the resulting objects will always be of the ContentApiModel type, so you may end up with a lot of unnecessary data in your resulting output. See Output model filtering.

See the MusicFestival template site for some examples of extending ContentModelMapper.

Output model filtering

By customizing ContentResultService, you can filter out properties from the data returned by Content Delivery API. This is called model filtering and has the benefit of decreasing your models. See How to customize API to change data returned to clients for more information.

Create custom controller

In the case where you have special requirements, you can create your own custom controller, and reuse those for different scenarios.

See also: Customized Transformation of IContent for ContentDeliveryApi by Vegard Solheim