Breeze can consume any standard OData feed “as is” when you configure the client for OData.
Breeze is not configured for OData services out of the box but it’s easy to tell Breeze that you want to talk to an OData source. The first step is to configure your Breeze application’s “data service adapter” which handles direct communication with remote data services.
The catch is that you have to pick the right adapter for your OData source. OData may be a “standard” but not all OData services are the same. They often diverge from the specifications in ways that can be painful for you.
We discuss the diversity of OData services (and the consequences) in a separate topic devoted to OData on the Server. Be sure to read it carefully.
Most industry standard OData services (including Microsoft’s WCF OData) should work with the “standard” OData data service adapter shipped in Breeze core. Configure your application to talk to this source before executing any Breeze server call. You might add this to your application bootstrapping:
// "Standard" Web API OData source (e.g., WCF OData)
breeze.config.initializeAdapterInstance('dataService', 'odata', true);
Breeze core ships with multiple OData service adapters. Be sure to pick the right adapter for your service!
The “standard” adapter you met earlier; it works with WCF OData.
There is an adapter for ASP.NET Web API OData v.3
breeze.config.initializeAdapterInstance('dataService', 'webApiOData', true);
MS introduced a breaking change in December 2014 with the Microsoft.AspNet.WebApi.OData v.5.3.1 nuget package. The v.1.5.5+ version of Breeze compensates for this by using absolute URLs for direct calls and inside $batch payloads
If you need to use relative URLs, (compatible with Breeze 1.5.4 and earlier), add relativeUrl = true to your adapter instance:
var ds = breeze.config.initializeAdapterInstance("dataService", "webApiOData");
ds.relativeUrl = true;
If you want to do custom URL mapping, set relativeUrl to your mapping function:
var ds = breeze.config.initializeAdapterInstance("dataService", "webApiOData");
ds.relativeUrl = function(dataService, url) {
return somehowConvert(url);
}
We also highly recommend the Pluralsight course "Building ASP.NET Web API OData Services" by Brian Noyes. The module, “Consuming OData Services …”, demonstrates consuming a Web API OData service with Breeze.
This Breeze client can retrieve standard OData metadata, submit standard OData query requests, and interpret the results as Breeze entities using the OData HTTP URI protocol.
Both of the aforementioned Breeze OData adapters depend upon datajs to handle lower level communications with OData sources. Be sure to include that script before Breeze.js itself.
We are working on an adapter for ASP.NET Web API OData v.4.
// ASP.NET Web API OData v.4
breeze.config.initializeAdapterInstance('dataService', 'webApiOData4', true);
It isn’t ready yet. Sadly, the breaking changes just keep coming and there still is no release of the Web API OData that supports the v.4 spec. You can learn more about this in OData on the .NET Server
The datajs client library does not work with OData v.4 sources; it’s only good for OData v.1-3.
You’ll need the JavaScript client library from Olingo. Be sure to include that script before Breeze.js itself.
We’ll have more to say about this when we release our adapter for OData v.4
Prior to Breeze v.1.5.5, you must specify an absolute path for your service address (AKA serviceName). Relative paths work for queries but not for saveChanges (prior to Microsoft.AspNet.WebApi.OData v.5.3.1). For example, you’d set the serviceName to “http://localhost:1234/odata” instead of just the odata web api fragment, “odata”.
Here is a general purpose approach to setting the serviceName to an absolute path:
var serviceName = window.location.protocol + '//' + window.location.host + '/odata/';
As of v.1.5.5, Breeze accepts either a relative or absolute serviceName. You’ll be able to write:
var serviceName = 'odata/';
You may still prefer to specify the absolute URL for your service address … and that’s fine with Breeze. The v.1.5.5 adapter converts all relative addresses to absolute addresses via webApiODataCtor.prototype.getAbsoluteUrl.
The Breeze OData DataService adapters rely on either the datajs or olingo OData clients to handle AJAX calls. If you need to add custom headers or otherwise manipulate the HTTP request, you’ll need to configure them appropriately.
With datajs, for example, you would configure OData.defaultHttpClient as described in the “Controlling AJAX calls” topic.
When you save entities, the entire change-set becomes a $batch request whose body consists of multiple nested HTTP requests, one per entity. The DataService adapters build these inner requests for you.
You can adjust the $batch details via each adapter’s changeRequestInterceptor.
We will be adding more dataService adapters for other popular sources. Stay tuned.
Free & open source