We value your privacy

We use cookies to enhance your browsing experience, serve personalised ads or content, and analyse our traffic. By clicking "Accept All", you consent to our use of cookies.

CustomiseReject AllAccept All

Customise Consent Preferences

We use cookies to help you navigate efficiently and perform certain functions. You will find detailed information about all cookies under each consent category below.

The cookies that are categorised as "Necessary" are stored on your browser as they are essential for enabling the basic functionalities of the site. ... Show more

NecessaryAlways Active

Necessary cookies are required to enable the basic features of this site, such as providing secure log-in or adjusting your consent preferences. These cookies do not store any personally identifiable data.

__cf_bm

Duration

1 hour

Description

This cookie, set by Cloudflare, is used to support Cloudflare Bot Management.

li_gc

Duration

6 months

Description

Linkedin set this cookie for storing visitor's consent regarding using cookies for non-essential purposes.

VISITOR_PRIVACY_METADATA

Duration

6 months

Description

YouTube sets this cookie to store the user's cookie consent state for the current domain.

cookieyes-*

Duration

1 year

Description

CookieYes sets this cookie for consent solution management.

Functional

Functional cookies help perform certain functionalities like sharing the content of the website on social media platforms, collecting feedback, and other third-party features.

lidc

Duration

1 day

Description

LinkedIn sets the lidc cookie to facilitate data center selection.

__Secure-ROLLOUT_TOKEN

Duration

6 months

Description

YouTube sets this cookie to manage feature rollout and experimentation. It helps Google control which new features or interface changes are shown to users as part of testing and staged rollouts, ensuring consistent experience for a given user during an experiment.

__Secure-YEC

Duration

past

Description

Description is currently not available.

__Secure-YNID

Duration

6 months

Description

YouTube cookie used to protect user security and prevent fraud, especially during the login process.

VISITOR_INFO1_LIVE

Duration

6 months

Description

A cookie set by YouTube to measure bandwidth that determines whether the user gets the new or old player interface.

ytidb::LAST_RESULT_ENTRY_KEY

Duration

Never Expires

Description

The cookie ytidb::LAST_RESULT_ENTRY_KEY is used by YouTube to store the last search result entry that was clicked by the user. This information is used to improve the user experience by providing more relevant search results in the future.

Analytics

Analytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics such as the number of visitors, bounce rate, traffic source, etc.

_seg_uid_17592

Duration

1 year

Description

Kit (formerly ConvertKit) uses SegMetrics that sets this cookie as a way to identify when users click links in our emails. No PII is collected by this cookie.

_seg_uid

Duration

1 year

Description

Kit (formerly ConvertKit) uses SegMetrics that sets this cookie as a way to identify when users click links in our emails. No PII is collected by this cookie.

_seg_visitor_17592

Duration

1 year

Description

Kit (formerly ConvertKit) uses SegMetrics that sets this cookie as a way to identify when users click links in our emails. No PII is collected by this cookie.

ai_sessionvoitanos

Duration

1 hour

Description

Microsoft Azure sets this cookie as a unique session identifier cookie, enabling counting of the number of users accessing the application over time.

ai_user

Duration

1 year

Description

Microsoft Azure sets this cookie as a unique user identifier cookie, enabling counting of the number of users accessing the application over time.

_ga_*

Duration

1 year 1 month 4 days

Description

Google Analytics sets this cookie to store and count page views.

_ga

Duration

1 year 1 month 4 days

Description

Google Analytics sets this cookie to calculate visitor, session and campaign data and track site usage for the site's analytics report. The cookie stores information anonymously and assigns a randomly generated number to recognise unique visitors.

_clck

Duration

1 year

Description

Microsoft Clarity sets this cookie to retain the browser's Clarity User ID and settings exclusive to that website. This guarantees that actions taken during subsequent visits to the same website will be linked to the same user ID.

_clsk

Duration

1 day

Description

Microsoft Clarity sets this cookie to store and consolidate a user's pageviews into a single session recording.

seg_domain_test

Duration

session

Description

Kit (formerly ConvertKit) uses SegMetrics that sets this cookie as a way to identify when users click links in our emails. No PII is collected by this cookie.

YSC

Duration

session

Description

YSC cookie is set by Youtube and is used to track the views of embedded videos on Youtube pages.

Performance

Performance cookies are used to understand and analyse the key performance indexes of the website which helps in delivering a better user experience for the visitors.

No cookies to display.

Advertisement cookies are used to provide visitors with customised advertisements based on the pages you visited previously and to analyse the effectiveness of the ad campaigns.

bcookie

Duration

1 year

Description

LinkedIn sets this cookie from LinkedIn share buttons and ad tags to recognize browser IDs.

_gcl_au

Duration

3 months

Description

Google Tag Manager sets this cookie to experiment advertisement efficiency of websites using their services.

_fbp

Duration

3 months

Description

Facebook sets this cookie to store and track interactions.

ckid

Duration

Never Expires

Description

Adara yield sets this cookie to deliver advertisements tailored to user interests on other websites and track transactions

test_cookie

Duration

15 minutes

Description

doubleclick.net sets this cookie to determine if the user's browser supports cookies.

Uncategorised

Other uncategorised cookies are those that are being analysed and have not been classified into a category as yet.

_rm_ctx

Duration

1 year

Description

Description is currently not available.

Reject AllSave My PreferencesAccept All

Voitanos is Closing October 1, 2026

Read the announcement, how it impacts customers, and 50% off everything!

Read The Announcement

articles

Getting BreezeJS to Work with the SharePoint 2013 REST API

[Development](/content/tags/development/ "View all posts tagged with 'Development'"/index.html) [Microsoft 365](/content/tags/microsoft-365/ "View all posts tagged with 'Microsoft 365'"/index.html) [SharePoint](/content/tags/sharepoint/ "View all posts tagged with 'SharePoint'"/index.html) [SharePoint 2013](/content/tags/sharepoint-2013/ "View all posts tagged with 'SharePoint 2013'"/index.html) [SharePoint 2016](/content/tags/sharepoint-2016/ "View all posts tagged with 'SharePoint 2016'"/index.html) [SharePoint 2019](/content/tags/sharepoint-2019/ "View all posts tagged with 'SharePoint 2019'"/index.html) [SharePoint SE](/content/tags/sharepoint-se/ "View all posts tagged with 'SharePoint SE'"/index.html)

by Andrew Connell

Last updated March 4, 2014

9 minutes read

Acquire the Breeze Library [Deep link anchor for 'Acquire the Breeze Library'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#acquire-the-breeze-library "Deep link anchor for 'Acquire the Breeze Library'"/index.html)

You first need to get the Breeze client-side library. This is provided as a NuGet package: Breeze.Client. For this you need the latest version (v1.4.9) which came out in late February 2014. This is by far the easiest step because you can skip it! You’ll see why in a moment…

Acquire the Breeze SharePoint Data Service [Deep link anchor for 'Acquire the Breeze SharePoint Data Service'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#acquire-the-breeze-sharepoint-data-service "Deep link anchor for 'Acquire the Breeze SharePoint Data Service'"/index.html)

Next, you need to get the Breeze SharePoint Data Service adapter. This is what Ward Bell, one of the brains behind Breeze, and I have been working on. It’s in a easy to grab NuGet package: Breeze.DataService.SharePoint. Best part is it already includes the Breeze client library package which is why you could ignore the previous step. It also includes a few other dependencies.

Once you’ve done this, add the necessary references to your HTML page, as shown here:

<script type="text/javascript" src="../Scripts/q.js"></script>
<script type="text/javascript" src="../Scripts/breeze.debug.js"></script>
<script type="text/javascript" src="../Scripts/breeze.labs.dataservice.abstractrest.js"></script>
<script type="text/javascript" src="../Scripts/breeze.labs.dataservice.sharepoint.js"></script>
<script type="text/javascript" src="../Scripts/breeze.metadata-helper.js"></script>

… just the HTML page with references

Configure Breeze to work with SharePoint [Deep link anchor for 'Configure Breeze to work with SharePoint'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#configure-breeze-to-work-with-sharepoint "Deep link anchor for 'Configure Breeze to work with SharePoint'"/index.html)

After you get everything, you then need to configure Breeze. This involves first initializing Breeze to use the new SharePoint data service adapter using the breeze.config.initializeAdapterInstance() function:

// configure breeze to use SharePoint OData service
var dsAdapter = breeze.config.initializeAdapterInstance('dataService', 'SharePointOData', true);

Then you need to tell Breeze how to get the security validation token, also known as the form digest, security digest, or the request digest. This is needed when you want to do an HTTP POST or DELETE against the SharePoint REST API. For this I’ll simply use the hidden form field added to the page:

// tell breeze how to get the security validation token for
//  HTTP POST & DELETE calls
dsAdapter.getRequestDigest = function () {
  return jQuery('#__REQUESTDIGEST').val();
};

OK… everything is all configured. Next up, tell Breeze about our entities.

Define your Entity Metadata Model [Deep link anchor for 'Define your Entity Metadata Model'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#define-your-entity-metadata-model "Deep link anchor for 'Define your Entity Metadata Model'"/index.html)

In this step you will build the metadata that tells Breeze about the list we want to work with. In my sample app I created a simple Contacts list in the app and to keep things simple, I only want to deal with the first and last names as well as the email address.

Writing the metadata can involve a good amount of code as you would expect. However over in the Breeze Labs there is a slick helper utility library called the Breeze Metadata Helper that helps quite a bit. I’ll add this via an easy to use NuGet package: Breeze.Metadata.Helper.

Then I’ll get a reference to the metadata helper and create an alias named addType() that will add the new entity type to the metadata store for me as well as set up a default select statement so I don’t have to deal with that in my code:

// create a new breeze metadata store
metadataStore = new breeze.MetadataStore();

// set up a helper to create entities
var namespace = '';
var helper = new breeze.config.MetadataHelper(
                    namespace,
                    breeze.AutoGeneratedKeyType.Identity);
// define a new function that uses the helper to
//  1) create a new entity type in the metadata store
//  2) create a default select so we don't have to create the
//    OData $select each time
var addType = function (typeDef) {
  var entityType = helper.addTypeToStore(metadataStore, typeDef);
  _addDefaultSelect(entityType);
  return entityType;
};

// add 'defaultSelect' custom metadata that selects for all
//  mapped data properties could be used by SharePoint dataservice
//  adapter to exclude unwanted property data in query payload
function _addDefaultSelect(type) {
  var custom = type.custom;
  // bail out if defined by hand already
  if (custom && custom.defaultSelect != null) { return; }

var select = [];
  type.dataProperties.forEach(function (prop) {
    if (!prop.isUnmapped) { select.push(prop.name); }
  });
  if (select.length) {
    if (!custom) { type.custom = custom = {}; }
    custom.defaultSelect = select.join(',');
  }
  return type;
}

Last but not least, I’m going to create an entity that maps to the contact list… take notice that I am not getting all fields from the contact list, just the ones I’m interested in. Oh, check out the email property… Breeze won’t let me save it unless it passes Breeze’s RegEx email address validation!:

// create entity for contacts
addType({
  name: 'Contact',
  defaultResourceName: 'getbytitle(\'Contacts\')/items',
  dataProperties: {
    Id: { type: breeze.DataType.Int32 },
    FirstName: { nullable: false },
    Title: { nullable: false },
    Email: {
      nullable: false,
      validators: [breeze.Validator.emailAddress()]
    }
  }
});

There are a few properties to take note of:

name: this is the name that we’ll use to reference our entity if we need to throughout our app
defaultResourceName: this is the endpoint for the list… not everything is listed here in the URL because as you’ll see, we’ll define the base part to the REST endpoint for the site in a moment
dataProperties: collection of the fields we want to get from SharePoint; notice some of these also include validation statements to enforce some data integrity

So with that, Breeze has been added to the page, configured and the metadata has been defined. Let’s now use it!

For more information on working with Breeze and SharePoint, check out my ~~upcoming~~ new Pluralsight course, ~~coming soon in March 2014~~ now available: Building SharePoint Apps as Single Page Apps with AngularJS. Module 5 is all about using Breeze with SharePoint.

Using Breeze with SharePoint 2013’s REST API [Deep link anchor for 'Using Breeze with SharePoint 2013’s REST API'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#using-breeze-with-sharepoint-2013s-rest-api "Deep link anchor for 'Using Breeze with SharePoint 2013’s REST API'"/index.html)

Before we start making calls, let’s first get an instance of something called the EntityManager. This is what will make the calls to the server for us. Part of this is also defining the data service, telling the SharePoint data service adapter to not request metadata from SharePoint’s REST API and what the root URL is in the REST API:

// init breeze for queries
function initBreeze() {
  // get reference to contact entity type
  contactType = metadataStore.getEntityType('Contact');

// create the data service
  var dataService = new breeze.DataService({
    // tell breeze the root REST endpoint to use
    //  since we only are using lists, point to that
    serviceName: _spPageContextInfo.webAbsoluteUrl + '/_api/web/lists/',
    // tell breeze not to interrogate sharepoint for it's
    //  massive OData $metadata response... we created it manually
    hasServerMetadata: false
  });

// create an instance of the entity manager
  entityManager = new breeze.EntityManager({
    dataService: dataService,
    // tell breeze where the metadata is
    metadataStore: metadataStore
  });
}

Now let’s see how to get data… for this I’ll fetch all the results from the contact list, using Breeze:

breeze.EntityQuery
  .from(contactType.defaultResourceName)
  .using(entityManager)
  .execute()
  .then(function (response) {
    var results = response.results;
    // write results > div
    if (results && results.length) {
      var message = '';
      for (var index = 0; index < results.length; index++) {
        message += results[index].FirstName
          + ' ' + results[index].Title
          + ' (' + results[index].Email + ')<br />';
      }
      jQuery("#results").html(message);
    }
  });

And if we wanted to get only one item, here’s how you do a filter:

breeze.EntityQuery
  .from(contactType.defaultResourceName)
  .using(entityManager)
  .execute()
  .where('Id', 'eq', 1)
  .then(function (data) {
    var message = data.entity.FirstName
        + ' ' + data.entity.Title
        + ' (' + data.entity.Email + ')<br />';
    jQuery("#results").html(message);
  });

What about updating items? Well all you do is get the item, make some changes and just call save!

// get the first item
var promise = breeze.EntityQuery
  .from(contactType.defaultResourceName)
  .using(entityManager)
  .execute()
  .where('Id', 'eq', 1)
  .then(function (data) {
    return data.entity;
  });

// update the first item
promise.then(function (contact) {
  contact.Title = 'NewName';
  entityManager.saveChanges().then(function () {
    jQuery("#results").html('saved first item in list');
  });
});

And deleting an item? This is similar to an update item:

// deletes the last item in the list
function deleteItem() {
  // delete the last item in the list
  breeze.EntityQuery
    .from(contactType.defaultResourceName)
    .using(entityManager)
    .execute()
    .then(function (response) {
      var results = response.results;
      var lastContact = results[results.length - 1];
      lastContact.entityAspect.setDeleted();
      entityManager.saveChanges()
        .then(function () {
          jQuery("#results").html('last item in list deleted');
        });
    });
}

And a very cool piece to this. Once you get items back from SharePoint which are stored in the Breeze local cache, you can re-fetch them at a later time without going to the server. The following call is effectively telling Breeze “get a contact with ID=1 from cache, but if you don’t find it, then go to the server to find it:”

// try to get a single item from the cache, then revert to server
entityManager.fetchEntityByKey('Contact', 1, true)
  .then(function (data) {
    var message = data.entity.FirstName
        + ' ' + data.entity.Title
        + ' (' + data.entity.Email + ')<br />';
    message += 'pulled from: ' + (data.fromCache ? 'cache' : 'server');
    jQuery("#results").html(message);
  });

Pretty slick huh? Again, remember what I said at the beginning of the post. I know you think “that was a lot of work at the start to configure and set it up.” I would agree with that to a point, but most of it is boilerplate code… everything except the creation of the metadata would be the same from one project to another.

Again… you can download the sample app I used to create this post from this public GitHub project I created: BreezeSP2013Sample. Just grab the code, open it in Visual Studio 2012/2013, change the Site URL property for the project to point to your SharePoint developer site (on-prem or Office 365) and hit F5 to see how it works! Hopefully you’ll find this as cool as I do… I can’t imagine working with SharePoint’s REST API without Breeze ever again! It just makes working with SharePoint’s REST API… well… a Breeze!

author

Andrew Connell

Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.

Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 22-year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.

[Andrew Connell](/content/pages/about-andrew/ "Andrew Connell"/index.html)Andrew Connell Andrew Connell on youtube Andrew Connell on linkedin Andrew Connell on bluesky Andrew Connell on reddit Andrew Connell on mvp

Feedback & Questions [Deep link anchor for 'Comments & Questions'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#feedback "Deep link anchor for 'Comments & Questions'"/index.html)

giscus

0 reactions

19 comments

· 40 replies

– powered by giscus

Oldest
Newest

WritePreview

Styling with Markdown is supported

vtns-comment-importer](https://github.com/apps/vtns-comment-importer) Jan 9, 2024

Originally posted by russell gove on 2014-03-06 17:58

Do yo think the adapter will work on 2010?

1 reply

Getting BreezeJS to Work with the SharePoint 2013 REST API

Acquire the Breeze Library [Deep link anchor for 'Acquire the Breeze Library'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#acquire-the-breeze-library "Deep link anchor for 'Acquire the Breeze Library'"/index.html)

Configure Breeze to work with SharePoint [Deep link anchor for 'Configure Breeze to work with SharePoint'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#configure-breeze-to-work-with-sharepoint "Deep link anchor for 'Configure Breeze to work with SharePoint'"/index.html)

Define your Entity Metadata Model [Deep link anchor for 'Define your Entity Metadata Model'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#define-your-entity-metadata-model "Deep link anchor for 'Define your Entity Metadata Model'"/index.html)

Feedback & Questions [Deep link anchor for 'Comments & Questions'](/content/blog/getting-breezejs-to-work-with-the-sharepoint-2013-rest-api/#feedback "Deep link anchor for 'Comments & Questions'"/index.html)

0 reactions

19 comments

·

40 replies

newsletter

Join 12,000+ developers for news & insights

BreezeJS makes client-side SharePoint REST dev easy.

Kirk Evans SharePoint 2013 Tokens Fiddler Extension

Microsoft Deprecates User Code Part of Sandboxed Solutions

bi-weekly newsletter

Join 12,000+ Microsoft 365 full-stack web developers for news, insights & resources. 100% free.