The OData Item Service

Last updated Tuesday, December 5, 2017 in Sitecore Experience Platform for Administrator, Developer
Keywords: Development

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/ 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

/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 an item including custom and standard fields

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

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)

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 'Ups')

/sitecore/api/ssc/aggregate/content/Items?$expand=Fields&$filter=Fields/any(f: f/Name eq 'Title' and f/Value ne 'Ups')

Search by several field values

/sitecore/api/ssc/aggregate/content/Items?$expand=Fields&$filter=Fields/any(f: (f/Name eq 'Title' and f/Value eq 'My Title') and (f/Name eq 'Text' and f/Value 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.

You can only sort by item properties.

Note

The OData Item Service uses the sorting features provided by the ContentSearch component. The ordering of items in search results can differ, depending on which provider (Solr, Lucene) is used for indexing.

The following examples show sort items:

Purpose

Syntax

Order by Name

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

Order by Name in descending order

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

Order by Name, then by Created

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

Implement paging in 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

Send feedback about the documentation to docsite@sitecore.net.