OData

The OData service document at the service root lists entry points: entity sets, singletons and opted-in function imports, each with a name and URL. The $metadata document describes the whole model in CSDL: types, keys, relationships, operations and annotations.

Customers 21 to 30 of those in Lyon, sorted by Name, plus the total number of Lyon customers. The service evaluates $filter, then $count, then $orderby, $skip and $top, whatever their order in the URL.

Put both inserts in one change set, a nested multipart/mixed part whose operations each carry a Content-ID. POST the order as Content-ID 1, then POST the lines to $1/Items; the service applies all of them or none.

An entity's ETag comes from the ETag header of a single-entity response or, per entity, the @etag control information (@odata.etag in 4.0). It goes back unchanged in If-Match on PATCH, PUT, DELETE or a bound action; stale gets 412, missing-but-required 428.

An OData entity type declares a key, so each instance has identity and can be addressed, created, updated and deleted on its own; a complex type is keyless and exists only as a property value inside the entity that holds it.

An OData function MUST NOT have observable side effects, must return data and is called with GET; an action may change state, may return nothing and is called with POST. Bound operations are called on a resource; unbound ones are static, reached mainly through container imports.

Support only what you can serve cheaply and fail the rest (unsupported options MUST be rejected, SHOULD with 501), advertise limits with Capabilities annotations such as FilterRestrictions and ExpandRestrictions, and cap every collection with server-driven paging.

OData's $batch packs many requests into one POST to the service root's $batch URL to save round trips. Its outer 200 OK only says the batch headers were valid and processing began; each inner request reports its own status.

An OData entity set is a named top-level collection of entities addressed by key; a singleton is a named top-level single entity addressed by its name alone, suited to one-per-service resources such as the order desk's settings or the caller's own profile.

Read the version header and the JSON envelope. OData v2 sends DataServiceVersion and wraps JSON in a "d" object with __metadata on each entry; OData v4 sends OData-Version (4.0 or 4.01) and puts a collection in a top-level "value" array.

One JSON object whose single error member holds code (service-defined, language-independent) and message (human-readable), plus optional target, details and innererror. An error after 200 OK is signalled by leaving the payload malformed, optionally with an OData-Error trailer.

The metadata format parameter sets how much control information the service writes. Minimal omits whatever metadata lets a client compute but keeps context, etag, count, nextLink and deltaLink; full writes every id, link and type explicitly; none keeps only nextLink and count.

OData's Prefer preferences are RFC 7240 hints: return=minimal asks for no response body, return=representation for the modified resource, respond-async for 202 Accepted plus a status monitor. A service must ignore preferences it does not support, so clients check the status and Preference-Applied.

An OData relationship is a NavigationProperty typed as another entity type or a collection of it. Partner names the inverse property that leads back; a NavigationPropertyBinding on the entity set says which entity set holds the related entities.

An OData annotation applies a vocabulary term to a model element, nested inside it or targeted from an Annotations block, with an optional qualifier. Core.Computed marks a property the service generates on insert and update; a value the client sends is ignored.

The any filter returns only customers who have at least one order over 500, with no orders inlined. The expand filter returns every customer, each carrying only its orders over 500 — possibly an empty list.

Put options in parentheses after the navigation property: Customers?$filter=City eq 'Lyon'&$expand=Orders($orderby=OrderDate desc;$top=5). The semicolon-separated nested options apply to each customer's own orders, not to the whole result.

An OData 4.01 service may return part of a collection with a next link; the client follows it unchanged until a page has none. Prefer: maxpagesize=N only requests a page size — the service may apply it or choose another.

Both lines pair a version header with a ceiling. In v2 a server answers with the lowest version that serves the request, capped by MaxDataServiceVersion; in v4 the service MUST answer with the greatest version it supports that does not exceed OData-MaxVersion.

A multipart OData batch runs in order and, by default, stops at the first error, which becomes the last part; the six missing requests never ran. Prefer: odata.continue-on-error asks the service to report the error and keep going.

Requests sharing an atomicityGroup must be adjacent and succeed or fail together. dependsOn names earlier ids or groups that must succeed first; anything undeclared may run in any order or in parallel, and a dependent whose prerequisite failed gets 424.

With ContainsTarget, each parent gets an implicit entity set of its contained entities: their keys need be unique only within that parent, their canonical URL is the parent's plus the property and key, and no top-level entity set may also hold them.

An OData client reads Capabilities vocabulary annotations on the entity set in $metadata: FilterRestrictions, SortRestrictions, TopSupported, InsertRestrictions and others. Absence means paging, counting and expand are assumed, inserts are not, and the service may still refuse a request.

Typed OData proxies generated from $metadata give compile-time checks but freeze the model; runtime discovery adapts but gives up types. Either way, clients must tolerate OData's safe additive changes and can detect drift through the metadata ETag and, in 4.01, $schemaversion.

Almost every client-visible surface breaks: payloads, query syntax, relationship URLs, the MERGE method, the model's associations and service operations. Run a v4 service at a new root beside v2, migrate clients one by one, and retire v2 once its traffic is gone.

In OData 4.01, CSDL XML (root edmx:Edmx) and CSDL JSON (one object with $Version and $EntityContainer) describe the same model; JSON omits defaults, and some defaults differ, such as nullability. A plain GET $metadata returns XML; application/json asks for JSON.

Nearly every structural assumption. OData v4 drops the "d"/"results" envelope and __metadata, reports counts and paging as @odata.count and @odata.nextLink, sends Int64 and Decimal as JSON numbers by default, writes dates as ISO 8601-style strings, and omits computable links.

With respond-async on the batch POST, the service may answer 202 Accepted with a status-monitor Location. Polling it can yield interim results: a multipart response ending in a 202 part, or a JSON response with nextLink. Change sets never return 202.

Send Prefer: odata.track-changes on the initial query; its last page carries a delta link instead of a next link. GETting that link, with the preference again, returns only added, changed and removed entities and a fresh delta link; 410 Gone means reload.