ODATA

ODATA Documentation: (opens new window)

OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming REST APIs. It enables creation of REST-based services which allow resources identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages.

General Overview

A OData-Url consist of the following 3 parts:

http://host:port/odata/syncjobs?$top=2&$orderby=Name
\____________________/\________/ \_________________/
          |                |              |
  service root URL    resource path  query options

• service root URL: the base path of the service
• resource path: the resource that is accessed or modified over Http methods.
• query options: Querystring parameters that are passed to run queries on the resource. Examples are:
  • $select
  • $filter
  • $top
  • $count
  • $orderby
  • $skip

More Query-Options can be found here: Query Options Overview (opens new window)

Getting Data

Data that has been received through a OData GET-Request will be returned as a Json-Object like the following:

GET /odata/syncjobs
{
  "value": [
    {
      "syncJobId": 1,
      "name": "Job1"
    },
    {
      "syncJobId": 2,
      "name": "Job2"
    }
  ],
  "@odata.nextLink": "..."
}

The actual value is stored in 'value', whereas '@odata.nextLink' might contain a link to retrieve more values if the endpoint is using paging and not all elements have been loaded.

Modifying data

To modify a OData resource, the specific endpoint has to be called with a DELETE, UPDATE, POST or PUT request. To create or modify existing resources, the data needs to be specified in the request body as a Json-Object and the Content-Type needs to be set to 'application/json'.

The following example shows how to update the Name of a syncjob through OData:

PUT /odata/syncjobs(1)?repository=repo1
Content-Type: application/json
{
    "name": "New SyncJob Name"
}