Using JSON Light with on premise SharePoint 2013

The returned payload from the SharePoint 2013 REST API endpoints is huge. On a default installation of SharePoint 2013, you need to use the following header for REST API calls to have JSON returned instead of the default XML:

With Service Pack 1, the support for JSON Light was added, which allows use of other odata settings than “verbose”, but this needs to be explicitly enabled. In the following sections I’ll show you why you should enable it, how to do it and a couple of things to watch out for.

What’s to gain by using JSON Light?

The default JSON payload is very verbose, and normally you won’t need all the extra information returned.

Here’s a quick test I did by using the Lists endpoint and the following REST API call:

Results by varying the odata value in the accept header:

“odata=verbose” – 141 kb
“odata=minimalmetadata” – 56,1 kb
“odata=nometadata” – 49 kb

That’s about 1/3 of the total response size when switching to “nometadata”! If your application relies heavily on the API, these numbers quickly add up.

How to enable JSON Light support

There are 2 prerequisites: SharePoint Server 2013 Service Pack 1 and WCF Data Services 5.6 installed to the global assembly cache. If you have installed SP2013 SP1 in a regular way, going through the standard prerequisite installer, everything should be ok. Otherwise you may have to install WCF Data Services 5.6 manually.

Verify your version of WCF Data Service by looking up the OData assembly version in the .NET 4.5 GAC location on one of your frontend servers. It should look something like this:

OData in GAC

If version 5.6 is not present it needs to be installed. WCF Data Service 5.6 is avaiable on this link, and make sure you enable GAC installation in the Options menu upon running the installer.

Now that the OData 5.6 assemblies are in place, we need to tell SharePoint to use these instead of the old version 5.0 dll’s. This can be done by adding this section to your web applications’ web.config files (content applications):

Add these in the “configuration/runtime” section, together with the other assembly redirects. Recycle your application pool, and that’s it. You should now be able to specify “Accept”: “application/json; odata=nometadata” in your request header and receive smaller payloads.

Note: changing the web.config file manually should only be done for testing purposes. You should script these changes and add them as part of your CI. An example script can be found here.

Gotchas

The root structure of the returned JSON varies depending on whether “verbose” or “nometadata/minimalmetadata” is used. The following structure is returned when using “odata=verbose”:

ResponseVerbose

While this is what you get from “odata=nometadata”:

ResponseNoMetadata

Remember to update your JSON parsing code accordingly. As stated in this article, the error object is also changed.

Also, if you specify “odata=nometadata” and WCF 5.6 has not been correctly installed, SharePoint will fallback to resonding with the default XML odata. If you have code that expects JSON this can lead to errors.

Sources/further reading

Office Blogs – JSON Light support in REST SharePoint API released

Platinumdogs blog on ODATA Minimal Metadata

TechNet article on enabling metadata formats for SP json

1 Response

  1. May 5, 2016

    […] SharePoint REST calls be a little less “chatty.” But, as Anders Austad points out, it must be enabled for use on-prem. (Also, it requires SharePoint 2013 Service Pack 1. You are on SP1 by now, […]

Leave a Reply

Your email address will not be published. Required fields are marked *