EntityService metadata exchange

Last updated Wednesday, August 16, 2017 in Sitecore Experience Platform for Developer
Keywords: Development

The JavaScript that manages calls to the EntityService on the server has to know about the properties of the entity class that it handles. The JavaScript layer can perform client-side validation of data assigned to the entity when it knows the type of the C# entity class and what validators are present on its properties.

The EntityService handler helps with this metadata exchange by listening for HTTP OPTIONS requests. When it finds an OPTIONS request, it will respond with a JSON-formatted HTTP response that describes the HTTP actions the service provides as well as a detailed description of the entity type the service operates on.

Before it makes any calls to the action endpoints of an EntityService, the JavaScript code makes a single HTTP OPTIONS call to receive the metadata for the service from the server.

This is an example of the metadata:

/**
 * Example of the metadata which indicates how to call.
 */
var MetdataAboutHowToCall = {
  "actions": {
    "GET": [
        {
          "FetchEntities": {
            "returnType": "Blog.Model.Blog[]",
            "properties": {}
          }
        },
        {
          "FetchEntity": {
            "returnType": "Blog.Model.Blog",
            "properties":{
              "key":"id",
              "datatype":"Guid"
            }
          }
        }
      ],
      "POST": {
        "CreateEntity": {
          "returnType": "void",
          "properties": {
            "key": "entity",
            "datatype": "Blog.Model.Blog"
          }
        }
      },
      "PUT": {
        "UpdateEntity": {
          "returnType": "void",
          "properties": {
            "key": "entity",
            "datatype": "Blog.Model.Blog"
          }
        }
      },
      "DELETE": {
        "Delete": {
          "returnType": "void",
          "properties": {
            "key": "entity",
            "datatype": "Blog.Model.Blog"
          }
        }
      }
    }
  };

The metadata also contains information about the Entity that can be sent to the server:

var entityMetadata = {
    "entity": {
      "key": "Id",
      "properties": [
        {
          "key": "Name",
          "datatype": "string",
          "validators": []
        },
        {
          "key": "Authors",
          "datatype": [
            [
              {
                "key": "Name",
                "datatype": "string",
                "validators": []
              },
              {
                "key": "Address",
                "datatype": [
                  {
                    "key": "Postcode",
                    "datatype": "string",
                    "validators": []
                  }
                ],
                "validators":[]
              }
            ]
          ],
          "validators":[]
        },
        {
          "key":"Created",
          "datatype":"datetime",
          "validators":[]
        },
        {
          "key":"State",
          "datatype":"number",
          "validators":[]
        },
        {
          "key":"Id",
          "datatype":"string",
          "validators":[]
        },
        {
          "key":"Url",
          "datatype":"string",
          "validators":[]
        }
      ]
    }
  };

EntityServiceJS sanitizes your data based on the metadata the server sends.

Action endpoints

The metadata returned by the OPTIONS request includes an actions object in the JSON response. This object has details about the method and associated method signatures for each of the HTTP verbs that the endpoint exposes.

For example:

"actions": {
    "GET": [
        {
            "FetchEntities": {
                "returnType": "entityType[]",
                "properties": {}
            }
        },
        {
            "FetchEntity": {
                "returnType": entityType",
                "properties": {
                    "key": "id",
                    "datatype": "Guid"
                }
            }
        }
    ],
    "POST": {
        "CreateEntity": {
            "returnType": "void",
            "properties": {
                "key": "entity",
                "datatype": "entityType"
            }
        }
    },
    "PUT": {
        "UpdateEntity": {
            "returnType": "void",
            "properties": {
                "key": "entity",
                "datatype": "entityType"
            }
        }
    },
    "DELETE": {
        "Delete": {
            "returnType": "void",
            "properties": {
                "key": "entity",
                "datatype": "entityType"
            }
        }
    }
}

where entityType is the C# type name of the EntityService.

Entity metadata

The OPTIONS request returns metadata that includes an entity object in the JSON response. This entity object provides details of the mapped C# entity type that the EntityService handles.

For example:

"entity": {
    "key": "Id",
    "properties": [
        {
            "key": "Name",
            "datatype": "string",
            "validators": []
        },
        {
            "key": "Authors",
            "datatype": [
                [
                    {
                        "key": "Name",
                        "datatype": "string",
                        "validators": [
                            {
                                "validatorName": "required",
                                "errorMessage": "Value is required"
                            },
                            {
                                "validatorName": "string",
                                "errorMessage": "Must be less than 50 characters in length",
                                "param": [
                                    0,
                                    50
                                ]
                            }
                        ]
                    },
                    {
                        "key": "Address",
                        "datatype": [
                            {
                                "key": "Postcode",
                                "datatype": "string",
                                "validators": []
                            }
                        ],
                        "validators": []
                    }
                ]
            ],
            "validators": []
        },
        {
            "key": "Id",
            "datatype": "string",
            "validators": []
        },
        {
            "key": "Url",
            "datatype": "string",
            "validators": []
        }
    ]
}

Note

You must derive all C# entity types that the EntityService handles from Sitecore.Services.Core.Model.EntityIdentity.

.NET to Javascript type mapping

Sitecore.Services.Client maps .NET types to JavaScript data types. This is the mapping translation for simple types:

.NET type

JavaScript data type

string

string

bool

boolean

int

number

float

number

double

number

long

number

DateTime

datetime

Guid

guid

Enum

number

Note

guid is not a JavaScript data type but the EntityService JavaScript layer understands it as an identity type and treats it accordingly.

Support for non-primitive types

The metadata for the entity description supports these non-primitive types:

  • Arrays
  • List< T > Generic collections
  • IEnumerable< T >
  • Classes and structs

An entity cannot contain a property of a type that is derived from Sitecore.Services.Core.Model.EntityIdentity.