Basic Concepts

Introduction to sensenet REST API

sensenet offers you a rich API allowing you to manage, integrate and deliver content on all types of clients, devices and platforms. This section explains the API structure and main concepts in more depth.

sensenet content repository is an OData producer which means your application can consume our OData service to create web and mobile apps or any other type of content based applications. It supports CRUD operations, properties, binary streams, paging options, custom queries and many more.

The requested resource can be any content in the repository (since everything is a content in sensenet, it could be really anything) that is permitted for the current user.

API endpoint

An OData HTTP request sent to the sensenet Content Repository contains the following parts:

  • protocol (http or https)
  • host (a site URL)
  • the OData.svc service name
  • the Path (or Id) of the requested resource
  • optional parameters
https:/example.com/OData.svc/[CONTENTPATH]

Query options

Query options are query string parameters a client may specify to control the amount and order of the data that a service returns for the resource identified by the URI. In sensenet there're two types of query options available OData System Query Options and custom sensenet query options. The OData standard query options' names are prefixed with a "$" character, sensenet query options should be used without a prefix.

option
$selectspecifies that a response from the service should return a subset of properties
$expandallows you to identify related entries with a single URI such that a graph of entries could be retrieved with a single HTTP request (e.g. creator user or any other related content)
$orderbyallows you to sort results by one or more properties, forward or reverse direction
$topidentifies a subset selecting only the first N items of the set
$skipidentifies a subset that is defined by seeking N entries into the collection and selecting only the remaining ones
$filteridentifies a subset determined by selecting only the entries that satisfy the predicate expression specified by the query option
$formatspecifies that a response to the request MUST use the media type specified by the query option (Atom and xml formats are not implemented yet in sensenet)
$inlinecountcontrols the __count property that can be found in every collection response
queryfilter the result collection using sensenet Content Query
metadatacontrols the metadata content in output entities

Accessibility

HTTP methods

The following HTTP methods can be used in requests to specify the expected operation:

method
GETgetting one or more entities. The URL contains all request information.
PUT/PATCHmodifying an entity. The URL defines the entity and the request body contains a JSON object. This object describes the properties and new values of the requested entity.
POSTcreating an entity. The URL defines the parent entity and the request body contains a JSON object. The URL determines the container of the new entity. The JSON object describes the properties and initial values of the new entity.
DELETEdeleting an entity. The entity (defined in the URL) and its children will be deleted.

Response

sensenet currently supports only the OData Verbose JSON response format, so the API response for a sensenet collection will look like the following:

{
"d": {
"__count": 10,
"results": [
{
"__metadata": {
"uri": "/odata.svc/Root/Content/IT/ImageLibrary('bagas-haryo-1415756-unsplash.jpg')",
"type": "Image",
...
},
"DisplayName": "bagas-haryo-1415756-unsplash.jpg",
"Path": "/Root/Content/IT/ImageLibrary/bagas-haryo-1415756-unsplash.jpg",
"Index": 5
},
{
"__metadata": {
"uri": "/odata.svc/Root/Content/IT/ImageLibrary('Sample-folder')",
"type": "Folder"
},
"DisplayName": "Sample folder",
"Path": "/Root/Content/IT/ImageLibrary/Sample-folder",
"Index": 2
},
...