Fabian Williams SharePoint Blog

Solving problems with SharePoint day and night

More on SharePoint 2013 REST API with Fiddler and SPD


Précis

So, as of lately when it comes to SharePoint 2013 Workflow, CSOM with Managed Code, REST API, I have been trying to see how far down the rabbit hole i can go, and talking about what I find.  As a result, I have been fielding quite a few questions on the topic; although there is quite a bit of information out there by Kirk (@kaevans) Evans here on MSDN and others, what i have find is that they discuss a lot of the Reading Data, usages in C# and JavaScript and they elude to debugging with Fiddler.  I on the other hand, like to test my work in Fiddler then take it into SPD (SharePoint Designer 2013) or Visual Studio 2012 for either work with Console Apps, Workflows, Event Receivers etc. It also gives me the opportunity to see what is happening under the layers of SPD, or obscured by Visual Studio Activities. Now there are times when that door will get slammed shut in you face especially around SharePoint Online Office365 and then i just rely on Wictor (@wictor )Wilens MSO Helper in a Console App to peruse around. This post will show you how to Add data into a SharePoint List (i.e. ListItem) using the REST API via Fiddler and How to Create a SharePoint LIST as i couldn’t find a decent example out there after suggesting to a work colleague that they use Fiddler to map out their work then do it in SPD. On the other hand, there is a great post here by Borislav Grgic on how to use Add an Item to a SharePoint List using the REST API and POST Method in SharePoint Designer 2013.

What Major Obstacles you will need to Overcome

This is what I found lacking when I did research on how to achieve the stated objectives above.  Most of the examples just told you to either “..type this” or “create a dictionary object to to that…”, and some just omitted major steps that you will get tripped up in and no way to circumvent it. So, taking this by the numbers, lets first assume that you want to get back some List data from SharePoint 2013, we will do this first On-Prem then In-Cloud (Office 365).

On Prem

  1. You will need to construct a Uri representing your target list such as :  //_api/lists/getListByTitle(‘’)/items">http://<site>/<web>/_api/lists/getListByTitle(‘<listNameHere>’)/items in a browser (preferably Chrome) or Fiddler
  2. You will need to set some Headers, specifically the (a) Accept and (b) Content-Type Headers to accept ‘application/json;odata=verbose’ inorder to work with the return items in JSON format which if you are using this in SPD, you MUST do in order to use the Dictionary Object, or if you want to read the data in some logical hierarchy.
  3. If you are ON Prem, and using Fiddler inside “Composer” under Options, i usually set the Automatically Authenticate Flag like so, you will see me talk about Decrypting HTTPS Traffic later on in the Cloud or HTTPS targets later on. In doing so your Cookie header will be automatically set.
    image
  4. Next ensure your Verb is set to GET and fire away.

In Da Cloud

  1. Well steps one (1) and two (2) are the same from the above, however step three (3) is a bit different.
  2. You will need to pass your Cookie Token for the Office 365 Site here, and simply put you will log into the Target Office 365 Site and using using Fiddler you set it to “Capture Traffic” after you log in. If/when you click on a List or Library as an example, inspect your Headers returned (assuming you have already gone under Tools / Fiddler Options and selected to Decrypt HTTPS Traffic) like so
    image
  3. Once you do and inspect the Headers you will find cookies for FedAuth and rtFa under the “Cookie” header. Go ahead and copy and paste that in the Request Headers section of Fiddler
  4. Next ensure your Verb is set to GET and fire away.

What if i want to POST (Add) Data to my SharePoint List?

Well, if you do, you have to do a few more things before you can actually POST that data.

  1. You will need to get the X-RequestDigest Header to send along with your POST, notice this is “not” a GET anymore. Now referencing the post again above by Kirk Evans if you look almost 3/4’s away down on the page or just Cntrl-F to find the word “contextinfo” you will find a description on how to get that Header Information in the d:FormDigestValue node.
  2. Essentially you will need to change your Fiddler VERB from a GET to a POST and send along an empty Request Body, you may need to set a “Content-Length” Request Header as well, and i usually do 104 for that length.
  3. You will get back the information that you will need to add to your Fiddler statement.
  4. In addition you will need to construct a Key/Value Pair (hence working in JSON) to pass along in the Request Content that you want to Add
  5. Now there is one more obscure piece of information that ususally trips people up that you will also need to do, and this information will form a part of your Request Content that holds your Data you are trying to add.
    1. When you did your GET for the site, there was a Node called (underscore undescore metadata) __metadata. You will need to take that value and pass it first ahead of any data you are trying to add. You will see this example below
  6. Once you do all the above, you ensure that your Verb is set to POST and fire away.

Lets look at a few Examples

So taking this from the beginning we will use a use case of a List i have called “AndyTaskListOnPrem” and we will first do some Gets, then a Post and then finally verify our work. Here is an example of the list before the exercise.

image

Next lets look at how you need to construct the GET to look at the data in JSON format in Fiddler

image

And our Outcome. Pay attention to the Metadata Node and the type = SP.Data.AndyTAskListOnPremListItem value. you will need this later on for the Adding of List Item.

image

continued

image

Next lets look at how to get the ContextData information.

Create a POST with the URI of /_api/contextinfo">http://<site>/_api/contextinfo as i have below

image

Ensure the Response Content is blank and execute that, your results should look like mine below. You will need to capture the “FormDigestValue” information for later on in your POST.

image

Next lets Create a List Item

Armed with that information we have enough to create a List Item in this SharePoint List using the
REST API and Fiddler and using the same information plug this into Dictionary Objects in SharePoint Designer along with the Make a HTTP Call to do the same, here’s how…

image

Paying attention to the POST Verb, the X-RequestDigest “Request Headers” and the __Metadata and Addition in the “Request Body” after execution the above you should get

image

a HTTP/1.1 201 Created response. and if we inspect the list we should expect to see

image

 

To round things off, lets assume our Target was Office 365 SharePoint Online, then we would expect to see our Headers contain our Auth Tokens.  I will take this to a next level by using an example someone just asked me about. I will Create a List in Office 365 “not list ITEM, an actual LIST” using the same methods described above. the KEY takeaway here is I need to Pass my Auth Tokens and ofcourse I am using a different REST API Call

Lets Create a SharePoint List using REST and Fiddler

So, in the spirit of openness, here is the REST call to get my Auth Token… well some of the token, I wasnt born yesterday 🙂

image

Here is the Context Info, key here is remember its not HTTPS and you need pass the Token as well.

image

Finally here is me creating A NEW LIST in the Web

image

and with all the confidence in the world [well this is O365 so we also cross our fingers] we expect to get a 201 Create Response back from HTTP Header

image

and visually in the browser we should expect to see

image

Summary

So, in this exercise we accomplished the following

  • Understanding of some of the SharePoint 2013 REST API
  • Usages of that API in Fiddler and the Browser
  • How to Add a SharePoint List Item using the REST API
  • How to create a new LIST using the REST API

This should translate VERY easily into SharePoint Designer 2013 and Visual Studio 2012, that is the point of the exercise. Thats why I am NOT showing how to do it there, I have other post that talk about the Dictionary Object and how to create Headers, just use what I have here and apply it to one of those post and you should be golden. This is me teaching to fish.. 🙂 Cheers.

 

Advertisements

September 3, 2013 - Posted by | JSON, Office 365, REST, SharePoint Designer 2013 | , ,

16 Comments »

  1. Way to put it all together. I love that you detailed each of the steps and took it through to creating list items and lists on both on premises and Office 365. Most every example I’ve seen only does 1/4 of this article!

    Comment by resing | September 4, 2013 | Reply

    • Thank you MCM Tom, appreciate your feedback. I kept getting questions on the topic and you are right, I couldn’t find something that told the complete story, so I decided to do one. Cheers mate, see u at the next event

      Comment by fabiangwilliams | September 4, 2013 | Reply

  2. Great very detailed article. Any samples on how to update a list item from SPD2013 using REST API?

    Comment by ElNa | September 6, 2013 | Reply

    • Its the same process except you do a PUT instead of a POST and you need to use the Etag Header.

      Comment by fabiangwilliams | September 6, 2013 | Reply

  3. […] my list. I’ve blogged about this topic and how I go about doing REST via SPD and Fiddler here and here and here, the first and last are probably most appropriate for this line of question. […]

    Pingback by HELP: Unable to Create List using SharePoint 2013 REST API in SPD2013 « Fabian Williams SharePoint Blog | September 6, 2013 | Reply

  4. Great article. Thanks a lot.
    I want to post to the current users newsfeed from a workflow by using the Sharepoint REST services for social.
    So for that can you please tell me how/what are the request parameters that I should add?

    Comment by Dilhari Anuruddika | September 27, 2013 | Reply

  5. Hi Fabian, i am new to sharepoint.. i read the articles but couldn’t understand what exactly REST is.. can you on simple english explain me what exactly the REST is ?? and is it a programming language, if so how it differs from C# and where it is located kinda stuff.

    Thanks in advance for sparing some time with me.

    Comment by kala | November 15, 2013 | Reply

    • here is a good example of what REST is in the context of how I use it http://msdn.microsoft.com/en-us/magazine/dd315413.aspx It provides a simple plain English definition of it and put it in context of Web Adoption. Its not a language as much as a API that enhances the HTTP protocol. the advantages is that you can connect to abstracted back end systems using web protocol so you don’t need to be concerned with Firewall, Rules, Networking etc.

      Comment by fabiangwilliams | November 15, 2013 | Reply

  6. Fabian,

    I am trying to create a calendar item using your method described above. I am able to use fiddler to POST an item to a SharePoint Online calendar. However, when I try to use a Call HTTP Web Service method (w/ SharePoint Designer 2013) nothing posts. I am fairly certain I have built my dictionaries of headers and parameters correctly (include x-requestdigest, content-length, authorization, etc.)

    Fiddler shows no traffic and SharePoint Online does not report an error. The only thing I can say is that the site that hosts the workflow and the site I’m trying to POST to are in different web applications. I thought that would not matter with the Auth Cookie.

    Any ideas?

    Thanks!

    Comment by Scott | November 19, 2013 | Reply

  7. Fabian, were you successful in updating or deleting items using SPD workflow and REST calls? I get the following error messages through SPD workflow or Fiddler: The type SP.ListItemEntityCollection does not support HTTP PUT method. The type SP.ListItemEntityCollection does not support HTTP DELETE method.

    Sorry to bother you again but web searches are showing no results and I’m out of ideas.

    Thanks and Happy Thanksgiving!

    Comment by Scott | November 27, 2013 | Reply

    • Yes I did, if you cant get it done via the methods I describe let me point you to this post that was helpful to me in creating my blog . you may have issues with your eTag, X-Match or some other header. http://msdn.microsoft.com/en-us/library/jj164022.aspx

      Comment by fabiangwilliams | November 29, 2013 | Reply

      • Fabian, I was able to figure it out. It wasn’t the headers. I was trying to call the REST API using a filter (?$filter=SourceID eq 28) in order to narrow down to one list item. I had to use the item id (_api/web/lists(‘xxxx’)/items(id)). This meant another HTTP GET call in the workflow (where I could use the filter above) to get the id and etag. it was fine to make an HTTP PUT/MERGE or DELETE call as long as I use the item Id in the URL.

        Thanks!

        Comment by Scott | December 3, 2013

  8. Fabian,
    I’ve followed your In Da Cloud directions to the letter. The Host, Accept, Content-Type headers are in place. I’ve formed the Cookie header from FedAuth and rtFA (did not encode them,) which was gained from logging in as a site collection admin. I’m only missing the Content-Length, but I’m not sure how to calculate that. I’m also missing any X-Request headers, but I thought those were for POST only. I’m testing with a simple call to url/_api/web/lists. No matter what I try, I’m still hitting authentication errors:

    {“error”:{“code”:”-2147024891, System.UnauthorizedAccessException”,”message”:{“lang”:”en-US”,”value”:”Access denied. You do not have permission to perform this action or access this resource.”}}}

    I can paste the URL into an address bar in the authenticated browser and get this just fine. I’m using the same login I pulled the cookie from. It just won’t work in the workflow.

    Comment by Jerry Cote | December 10, 2013 | Reply

    • Just to make sure I am understanding you correctly. your account that you are using is a SCAdmin to the /url/_api/web/lists right? and it is those creds that you took and put in the header under a workflow variable called Cookie of type String remember it may say Cookies in Fiddler but the header is Cookie in real live no (s) all in all you need a “Accept”, “Content-Length” header both of application/json;odata=verbose then you need a Cookie header, a Host header which is the fqdn of your site and a content length of which I usually use 225 as an arbitrary number. with that you should be good to go. and they are all string workflow variable types.

      If all of that is true, can you make this work in Fiddler? under the same data?

      Comment by fabiangwilliams | December 10, 2013 | Reply

      • Thank you Fabian. That’s correct. Using the Fiddler Composer, I get the full lists detail in the response, using this GET and these headers:

        GET https://wbinc.sharepoint.com/_api/web/lists (HTTP 1.1)

        Accept:application/json;odata=verbose
        Content-Type:application/json;odata=verbose
        Cookie: rtFa=<>;FedAuth<>
        Host: wbinc.sharepoint.com
        Content-Length:225

        But the same values in the request headers of workflow http web service returns an authentication error. I log the ResponseContent, which always comes back as shown:

        {“error”:{“code”:”-2147024891, System.UnauthorizedAccessException”,”message”:{“lang”:”en-US”,”value”:”Access denied. You do not have permission to perform this action or access this resource.”}}}

        Comment by Jerry Cote | December 10, 2013


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: