EntityService metadata exchange

Abstract

Describes how to set the properties of an entiry class.

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.