Understanding SharePoint 2013 REST API Responses

Technorati Tags: SP2013,Apps,Dev,VS2013,VS2012

I have been using the SPRemoteAPIExplorer Visual Studio Extension a lot. It has been a great help in understanding what inputs are required when making endpoint calls. Of course it is incredibly easy to generate the actual jQuery code with the new 2.0 feature.  However, something was missing. When I started using REST the more I discovered that the responses sent back were difficult to navigate. It took multiple steps to visualize what the responses looked like using either the browser developer tools or the new Visual Studio JSON visualizer. This was slowing down my development. It would be nice to know what to expect from a REST call so I could write the code to get what I wanted. The MSDN documentation is getting better but the response documentation is sparse, or the JSON shown is hard to understand. So to make my REST development much more productive I decided to add the responses for remote calls to the SPRemoteAPIExplorer in version 2.5. I also added the ability to copy the JSON path from a response to so you can copy it directly into your code. Having to remember the deeply nested JSON path of a response property can be daunting and error prone since the JSON path is case sensitive. For example, the REST response from the postquery method when searching returns an undocumented complex type. This type has many nested complex types. Trying to figure out where or if the data in a response exists could be an hour long web search or a lot of stepping through code and using visualizers. This can be much easier.

 

Copy the JSON Path

You can right click on any part of a response and select the “Copy Response Path” menu item. This will generate the JSON path to be used in your code. This feature is immensely helpful if you don’t know the rules of how different response types are returned. For example all “multivalue” types are returned as object arrays in JavaScript. The items are always included in an array named “results”.  Multivalued types include “Feeds”, “Arrays” and “Collections”. All three of these types are possible responses in the SharePoint Remote API.  Another unknown rule when getting JSON responses is that the method name is included in the JSON when the response is either a complex type or a primitive type. The example below shows that the “postquery” method name is appended because it returns a complex type.

Here is the output:

data.d.postquery.PrimaryQueryResult.RefinementResults.Refiners.results[0].Entries.results[0].RefinementCount

REST Response Types

Rest responses come in three flavors. Below are the icons used to display them in the response. Each type has a corresponding “multivalued” icon.

Primitives of course are string, integers, boolean and date. Complex types are types that are not defined in the entity model but are used as parameters to methods or returned in responses. Entities are the entities defined in the SharePoint Remote API model and can have both properties and methods. Entities returned as arrays or collections are considered feeds. When expanding any of the multivalued type icons you will see the properties of the underlying child item and not the properties of the collection itself.

The Complexity of Responses

As you use this tool you will discover that complex types can be embedded in entities. Many of the complex types are undocumented and internal within the object model. This tool will give you 99% reliable and accurate information on how to use and consume the SharePoint Remote API.  The other 1% like a “DataTable” in the Table property of a RelevantResult returned by search are hard coded and are not exposed. I am working on fixing that. In the meantime, with this release I have also fixed the generation of $ajax jQuery calls for methods that are tagged as “IntrinsicRestFul”. These method types were discussed in a previous post. Intrinsic RestFul. SPRemoteAPIExplorer has made my REST API coding incredibly productive. With the new Response and Response Path features it should be even easier for you.