The OData Item Service

Version: 10.0

You use the OData Item Service for read-only access to Sitecore items. The service authenticates requests using API keys. The service exposes the /sitecore/api/ssc/aggregate/content/Items endpoint. It returns data in OData (JSON) format.

This topic describes:

The request security context

Sitecore runs requests to the OData Item Service in the security context of the current Sitecore user.

You can access the OData Item Service anonymously. Sitecore runs anonymous requests in the security context of the user defined in the Sitecore.Services.AnonymousUser configuration setting. Such requests use user impersonation and run as the sitecore\ServicesAPI user by default.

Using API keys

You must pass an API key along to the OData Item Service with all requests. You pass the API in a GET request. For example:

sitecore/api/ssc/aggregate/content/Items('{<item id>}')?sc_apikey=<api key>

The OData Item API Key template introduces two fields used by the OData Item Service:

Field

Description

Example

Database

Specifies the name of the database to retrieve items from. This field is required.

web

Search Filter

Specifies search options in OData filter format. The OData Item Service adds the values to the value of the $filter parameter, using the and operator. This field is optional.

TemplateName eq 'Sample Item'

Standard value: IsLatestVersion eq true (returns only latest version of items)

Fields are case-sensitive.

Retrieving items

The tables in the following subsections show how you perform a number of common GET requests to the OData Item Service. For brevity, the API key is not shown in the syntax.

Getting item by key

These requests retrieve one or more items.

Purpose of request

Syntax

Retrieve an item that is identified by item ID

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')

Retrieve an item that is identified by path

/sitecore/api/ssc/aggregate/content/Items('/sitecore/content/Home')

Retrieve an item including custom fields

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=Fields

Retrieve custom field values (name/value field format)

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues

Retrieve an item including custom and standard fields

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=Fields, StandardFields

Retrieve custom and standard field values (name/value field format)

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues, StandardFieldValues

Retrieve all children of an item

/sitecore/api/ssc/aggregate/content/Items('/sitecore/content')/Children

Retrieve the parent of an item

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')/Parent

Retrieve specific language version of an item

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?language=ja-JP

Retrieve specific version of an item

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?version=2

Get Item with property projection (provide only specified item properties)

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?$select=Id,Name,TemplateName

Get Item with field projection (provide only specified field properties)

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?expand=Fields($select=Name,Value)

In Sitecore 9, Update 2, and later, use this instead:

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues($select=Title,Text

These requests use Sitecore content search to search for items, and the OData Item Service search has the same features as content search in general.

Purpose of request

Syntax

Search by item property

/sitecore/api/ssc/aggregate/content/Items?$filter=Name eq 'Home'

Search by multiple item properties

/sitecore/api/ssc/aggregate/content/Items?$filter=Name eq 'Home' and TemplateName eq 'Sample Item'

Search by field value (the example retrieves items where the field Title is not equal to 'Welcome')

/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title ne 'Welcome'

You are not required to expand the property you are filtering by. For example, you can filter by the FieldValuesproperty but expand Fields:

/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title ne 'Welcome'&amp;$expand=Fields

Search by several field values

/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title eq 'My Title' and FieldValues/Text eq 'My text'

Search by date and time

/sitecore/api/ssc/aggregate/content/Items?$filter=TemplateName eq 'Sample Item' and Updated ge 2017-03-22T10:42:00Z

You can use these OData operators:

Operator

Description

eq

equal

ne

not equal

gt

greater than

ge

greater than or equal

lt

less than

le

less than or equal

and

logical and

or

logical or

not

logical negation

You can use these OData string functions:

  • contains

  • startswith

  • endswith

Sort search results

You can sort search results with the $orderby query option. You can specify multiple properties to sort by, using a comma as a separator. The default sorting order is ascending. You can change the sorting order by adding the desc keyword after the property name.

Note

The OData Item Service uses the sorting features provided by the ContentSearch component.

The following examples show sort items:

Purpose

Syntax

Order by a property

/sitecore/api/ssc/aggregate/content/Items?$orderby=Name

Order by a property in descending order

/sitecore/api/ssc/aggregate/content/Items?$orderby=Name desc

Order by multiple properties

/sitecore/api/ssc/aggregate/content/Items?$orderby=Name, Created

Order by a field value

/sitecore/api/ssc/aggregate/content/Items?$orderby=FieldValues/Color

Paging search results

You restrict the number of items in search results with the $skip and $top options. You use the $skip option to skip the indicated amount of items from the result. You use the $top option to limit the number of items in the result.

You can use a combination of $skip and $top to retrieve a paged collection.

The following examples show how to do paging on a result:

Purpose

Syntax

Get the top 3 items

/sitecore/api/ssc/aggregate/content/Items?$top=3

Skip the first item and get the rest of the items

/sitecore/api/ssc/aggregate/content/Items?$skip=1

Skip three items, then get three items

/sitecore/api/ssc/aggregate/content/Items?$skip=3&$top=3

Field format

The OData Item service provides fields in two formats:

  • Field as object (Fields and StandardFields properties)

  • Field as name/value pair (FieldValues and StandardFieldValues properties)

All spaces in field names are replaced with an underscore (“_“).

Fields and StandardFields

The OData Item service provides the values of the Fields and StandardFields properties as a collection of field objects.

RequestResponse
"Fields": [
    {
        "Id": "5ab98be3-5e38-4cbf-95cf-0cb8d1929247",
        "Name": "Text",
        "Value": "Welcome to Sitecore",
        "Type": "Single-Line Text",
        ...
    },
    {
        "Id": "b293759d-9a2a-40d2-bb34-46e03952d3e9",
        "Name": "Number",
        "Value": "53",
        "Type": "Integer",
        ...
    },
    {
        "Id": "0b4ffcc9-153c-4de7-8563-2049cf1c933b",
        "Name": "Image",
        "Value": "<image mediaid=\"{04DAD0FD-DB66-4070-881F-17264CA257E1}\" alt=\"This is alternate text\" height=\"\" width=\"\" hspace=\"1\" vspace=\"2\" class=\"ImageClass\" />",
        "Type": "Image",
        ...
        "Url": "/-/media/Default-Website/cover.ashx",
        "Alt": "This is alternate text",
        "Width": "1600",
        "Height": "550",
        "Vspace": "2",
        "Hspace": "1",
        "Class": "ImageClass",
        "MediaItemId": "04dad0fd-db66-4070-881f-17264ca257e1"
    }
]

Image fields

The OData Item service provides additional properties for image fields (URL, Alt, and so forth).

FieldValues and StandardFieldValues

The Odata Item service provides the values of the FieldValues and StandardFieldValues properties as a simple object. The properties of this object represent the fields (field name and value):

RequestResponse
"FieldValues": {
    "$count": 3,
    
    "Text": "Welcome to Sitecore",
    
    "Number": "53",
    
    "Image": "<image mediaid=\"{04DAD0FD-DB66-4070-881F-17264CA257E1}\" alt=\"This is alternate text\" height=\"\" width=\"\" hspace=\"1\" vspace=\"2\" class=\"ImageClass\" />",
    
    "Image__Url": "/-/media/Default-Website/cover.ashx",
    "Image__Alt": "This is alternate text",
}

$count is a service property that indicates how many fields an item has.

Image fields

The OData Item service provides additional properties for image fields (URL, Alt, and so forth).The following format is used for names of extra properties: <field-name>__<extra-name>.

Do you have some feedback for us?

If you have suggestions for improving this article,