Sitecore.Services.Client

The OData Item Service

Version:

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`

Item search

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'&$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.

"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):

"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>.

If you have suggestions for improving this article, let us know!