Odata

OData v4 Protocol Support

Open Data Protocol (OData) v4 is an industry-standard protocol for building and consuming RESTful APIs. It provides a uniform way to expose, structure, query, and manipulate data.

Overview

OData v4 provides standardized URL conventions for querying data including:

$select: Choose which fields to return
$filter: Filter results with complex expressions
$orderby: Sort results
$top/$skip: Pagination
$expand: Include related entities
$count: Get total count

Use Cases

Enterprise Integration
- Integrate with Microsoft Dynamics 365
- Connect to SharePoint Online
- SAP OData services
API Standardization
- Provide consistent query interface
- Standard pagination and filtering
- Industry-recognized protocol
External Data Sources
- Connect to OData-compliant systems
- Federated queries
- Data virtualization

@example OData Query

GET /api/odata/customers?
  $select=name,email&
  $filter=country eq 'US' and revenue gt 100000&
  $orderby=revenue desc&
  $top=10&
  $skip=20&
  $expand=orders&
  $count=true

@example Programmatic Use

const query: ODataQuery = {
  select: ['name', 'email'],
  filter: "country eq 'US' and revenue gt 100000",
  orderby: 'revenue desc',
  top: 10,
  skip: 20,
  expand: ['orders'],
  count: true
}

Source: packages/spec/src/api/odata.zod.ts

TypeScript Usage

import { ODataConfigSchema, ODataErrorSchema, ODataFilterFunctionSchema, ODataMetadataSchema, ODataQuerySchema, ODataResponseSchema } from '@objectstack/spec/api';
import type { ODataConfig, ODataError, ODataFilterFunction, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api';

// Validate data
const result = ODataConfigSchema.parse(data);

ODataConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable OData API
path	`string`	✅	OData endpoint path
metadata	`{ namespace: string; entityTypes: object[]; entitySets: object[] }`	optional	OData metadata configuration

ODataError

Properties

Property	Type	Required	Description
error	`{ code: string; message: string; target?: string; details?: object[]; … }`	✅

ODataFilterFunction

Allowed Values

contains
startswith
endswith
length
indexof
substring
tolower
toupper
trim
concat
year
month
day
hour
minute
second
date
time
now
maxdatetime
mindatetime
round
floor
ceiling
cast
isof
any
all

ODataMetadata

Properties

Property	Type	Required	Description
namespace	`string`	✅	Service namespace
entityTypes	`{ name: string; key: string[]; properties: object[]; navigationProperties?: object[] }[]`	✅	Entity types
entitySets	`{ name: string; entityType: string }[]`	✅	Entity sets

ODataQuery

Properties

Property	Type	Required	Description
$select	`string \| string[]`	optional	Fields to select
$filter	`string`	optional	Filter expression (OData filter syntax)
$orderby	`string \| string[]`	optional	Sort order
$top	`integer`	optional	Max results to return
$skip	`integer`	optional	Results to skip
$expand	`string \| string[]`	optional	Navigation properties to expand (reference fields: lookup/master_detail/user/tree)
$count	`boolean`	optional	Include total count
$search	`string`	optional	Search expression
$format	`Enum<'json' \| 'xml' \| 'atom'>`	optional	Response format
$apply	`string`	optional	Aggregation expression

ODataResponse

Properties

Property	Type	Required	Description
@odata.context	`string`	optional	Metadata context URL
@odata.count	`integer`	optional	Total results count
@odata.nextLink	`string`	optional	Next page URL
value	`Record<string, any>[]`	✅	Results array

On this page