OData

Introduction

OData is a standardized protocol for consuming Web APIs. OData builds on core protocols like HTTP and commonly accepted methodologies like REST. OData is a standard protocol to query RESTful web serivces and supports filtering, sorting and paging.

WebConnect.OData is a OData version 4.0 web service and supports OData queries for all data types. The result is always in application/atom+json format. The OData standard does not currently provide for xml. On this page the common features of OData queries are discussed based on some examples. For more information about OData see http://www.odata.org/.

Tables and fields

The available tables and field names can be found in Venice by starting the module 'ODBC file descriptions' and from there selecting Home - File descriptions - Field information. Before you can access the data from a Venice dossier via OData, you must first activate WebConnect for the dossier from Venice.

Request

The request url contains the following parts:
Part Name Comment
https Protocol The web service is always accessed by a secure connection.
venice.unit4.com Host name The label that is assigned to identify the device that is hosting the web service.
webconnect.OData Web service name The name of the web service.
odata Part of the route for the API calls.
Demo Dossier id The identification of the dossier.
CST Table The technical name of the Venice table.
$select=Name Parameters The OData query options.
Remark:
  • The parameters are optional.
  • The parameters must be url encoded.
The following example gets the name of all the customer cards.
https://venice.unit4.com/WebConnect.OData/odata/Demo/CST?$select=Name

Request header

The request header is an extra piece of information that is send to the web service. It contains metadata or details required for executing the request.

Name Description
Authorization Specify the Aspex username and password via basic authentication.
In this JavaScript example we pass our credentials.
var request = new XMLHttpRequest();
...
request.setRequestHeader("Authorization","Basic " + Base64.encode ("User:Password"));
...

Examples

It is not our intention to provide a comprehensive manual. We will give only a few of the most used options that OData offers, to get you started quickly. You can find more possibilities via http://www.odata.org/

$filter

Use the "$filter" query option to reduce the number of table rows/records that are returned to only those that match the filter expression'. The expression language that is used in $filter, supports references to properties and literals. The literal values can be strings enclosed in single quotes, numbers and boolean values (true or false). For more information see the $filter documentation.

The following example gets the customer cards with name 'My customer NV'.
https://venice.unit4.com/WebConnect.OData/odata/WebConnect/CST?$filter=Name+eq+'My+customer+NV'

$select

Use the "$select" operator to limit the returned fields from a table. For more information see the $select documentation.

The following example gets the name and the address of all customer cards.
https://venice.unit4.com/WebConnect.OData/odata/WebConnect/CST?$select=Name,Street,PostalCode,City,CountryCode,CountryName