We’ve talked about SharePoint’s REST API before, but today I want to share a couple of tips for testing and playing with the REST API.
The REST API is one of several ways to automate SharePoint tasks, and it is especially useful in workflows because as of SharePoint 2013, workflows can make calls to web services. This means we can make calls to the REST API from a workflow. The REST API supports a large number of actions that we can’t do with the out-of-the-box workflow actions, so by making calls to the REST API from workflows, we greatly increase the number of actions we can do from workflows without having to write custom code.
Our “no code” solution for creating sites from a workflow is an example of leveraging the REST API in this way.
The REST API is of particular interest when working with SharePoint Online, because we can’t upload workflow custom activities to SharePoint Online that use custom code.
Often before you start integrating web service calls into your workflows, you will want to test the calls you are making to verify they are correct. The rest of this blog post will offer some tips on testing the SharePoint REST API. I will not go into greater detail on the REST API itself.
Tools
First, let’s look at some tools we can use to make sending REST requests easier.While it is somewhat easy to send GET requests to the REST API, much of the power comes from being able to add and modify data using POST requests. To send POST requests, you’ll want to use a tool.
Browser Plugins:
The first class of tools you can use are browser plugins. Two examples for Chrome are Advanced REST Client and Postman REST Client. One advantage of browser-based plugins is that they make authentication easier. If you’re connecting to the REST API of a SharePoint Online site, then once you’ve logged in via your browser, you don’t need to worry about authentication any more.
Other tools:
SoapUI and Fiddler are both free tools for web developers that can be used to test REST APIs.
HTTP Headers
Next, let’s look at some of the HTTP headers that are most relevant in SharePoint REST requests.
Cookie
If you’re using a tool like SoapUI or Fiddler to send REST requests to SharePoint Online, you will notice that you can’t use the built-in authentication mechanisms. However, what you can do is log into SharePoint Online and then grab the cookies that were set by SharePoint Online. These are FedAuth and rtFa. If you add these to cookie values from your authenticated browser to the Cookie header in SoapUI or Fiddler, you will be authenticated.
Accept and Content-Type
The SharePoint 2013 Call HTTP Web Service workflow action uses JSON for encapsulating its requests and responses. So when you’re testing the SharePoint REST APIs, you’ll probably want to make sure you’re sending and receiving JSON data. To tell SharePoint you want its response formatted as JSON, set the “Accept” header of your request to “application/json; odata=verbose”. When sending a JSON request to SharePoint, make sure to set the Content-Type header to “application/json; odata=verbose”.
X-RequestDigest
One feature that SharePoint uses to prevent Replay Attacks is the Request Digest Header. Any time you send a POST request to the SharePoint server, it expects to see a valid Request Digest header. If your request does not include one, you will get a 403 error and the following message:
The security validation for this page is invalid and might be corrupted. Please use your web browser's Back button to try your operation again.
So how do you get a valid Request Digest header? SharePoint sends one in the headers of every response to a POST request:
You can also get a Request Digest by submitting a POST request to _api/contextinfo and parsing the response. Each Request Digest can only be used once, and you use it by setting the X-RequestDigest header of your POST request.
If-Match
If you’re trying to use the REST API to update a list or library item, you may encounter the error message
The request ETag value '' does not match the object's ETag value.
SharePoint uses the ETag header to ensure that when you update an item, you’re updating the latest version of an item. This is to prevent you from making changes to an item that has been modified since you last read it.
If you see this error message, you will need to send a If-Match header with your request that matches the ETag of the item you’re trying to update. So for example, when you query a list item, the response will include some metadata like this:
{
"__metadata": {
"id": "Web/Lists(guid'2f134a51-8db0-4010-b537-48e3e9c0a3cb')/Items(1)",
"etag": "\"2\""
}
If you set your If-Match header to “2” then SharePoint will allow your update, so long as nobody has updated the item since you read it. Note that the quotes around the ETag number need to be included.
I hope these tips are useful to you.
Learn more about DMC's SharePoint consulting services.