Now that the administrative details of Part 2 are over we can now address some useful issues. Recall that if we query a List we can obtain the uri segment needed to access the items in the list. This for example would return all items the referenced list:
Please see this post for an important update about data pages when using the …/Items call
If we don’t want all the items we can apply an OData $filter verb to select a subset of items matching some criteria. If we want a subset of items with a specific Author we could create the following fragment:
Web/list(guid’850fae4-0cce-8c30-c2a85001e215’)/Items?$filter=Author eq ‘Cloud2013’
If you are concerned about download sizes of your calls into the REST API you can limit the property fields returned using the OData $select verb.
The feed returned from a GET call with an uri fragment like that above has an identical structure to the feed discussed in Part 2 of this series. Depending on the list and the $filter there may be zero, one or many entry nodes. Each entry node contains information on one Item with its corresponding Links collection and properties collection. In this case the Link collections refers to operations which can be made this single item, for example the “ContentType” Link (Web/Lists(guid’850f0ae4-0cce-47e9-8c30-c2a85001e216′)/Items(3)/ContentType) would return a feed with an entry for links and properties associated with the content item for this item. The properties collection is, of course, the fields for an item and the values associated with that item. Here is a Quick Watch screen snap of the data for an item:
This looks pretty normal. The field “Title” appears with its value “Points To Approved Item”. Some of the field names have been Sharepointerized. Our field “AIC Description” has become “AIC_x0020_Description”. What is going on here? According to this post:
When you create a column on a list, both its DisplayName and StaticName are set to the same value. However, the StaticName contains converted values for some characters, most notably a space ‘ ‘ is converted to
'_x0020_'. So if the DisplayName is ‘Product Description’, then the StaticName will be
There’s another little bugaboo: The StaticName is limited to 32 characters including the translations for special characters.
In translation, the DisplayName is the name you see on the Sharepoint UI screen. The value of the display name can change. When the column is created a fixed “StaticName” is created equal to the initial DisplayName with spaces converted to _x0020. When working with the REST API we are seeing the StaticName. Ok so far? We have another problem some fields are missing! The REST API does not support all columns using the
format above. This interesting post has more details.
So we will need to do some more digging Sharepoint has to store the value somewhere. Well, in the true spirit of Sharepoint we have to say: it depends. In our case we us a Publishing Hyperlink field. This is a field which allows a list item to contain a reference to some other object. That object can be:
an external Web URL
a Sharepoint Page; or
A Document stored in a Sharepoint Document Library
BTW, in the first instance the whole URL is stored and in the later two instances only the RELATIVE link is stored since these are assumed to point to a SP page or document within the current site. At our site we need to retrieve the true value of the Publishing Hyperlink. And as you can see from the above the field (which we call “AIC Publishing Hyperlink”) does not appear in any form in the original REST call. If we jump to the Links collection for an item we can find a link called: FieldValuesForEdit. In our case this is:
If we call that link we get back an entry which in Quick Watch looks like:
OK, there it is, hiding in Sharepointification form as “AIC_x005f_x0020_x005f_Publishing_x005f_x0020_x005f_Hyper” (where did the _X005f come from you might ask. I have no idea, some things in SP I just accept). The value is a HTML anchor tag and it is pretty simple to parse these to recover the href value. Which in this case is (after decoding) “/DLR%20Document%20Library/1969.html” where ““/DLR%20Document%20Library/” points to a Sharepoint Document Library and 1969.html as the Document. We are working on how Managed Metadata values are stored but our research is not yet complete on this. In my next post I will discuss how to download and upload a document from a document library (which is how I fell into this problem of retrieving the value stored in a Publishing Hyperlink field.
Ok, we are almost done for today. Let’s look at a security issue. What values you see for a field on an item depends on the identity of user making the REST API call and the state of the item within Sharepoint when you look at it (it’s a Quantum thing). Recall the publication settings for a list item in Sharepoint. This screen snap may help your memory:
When we enable Content Approval and set “Who should see draft items” to Only users who can approve items (and the author of the item)” then an item can exist in two states at once. If we have an approved item then everyone sees the same thing:
No if an editor changes an item, say by changing the content of the “Description” field and the item is waiting for approval the item is in a Pending Approval Status like this:
If you are a general user you see the values in the Approved item. If you are an approver or the author you see the values in the Pending Item. As in the UI so in the REST API. The values returned to you in your REST API call depend on the Sharepoint security group of the identity you use to access the item and the list settings for approval and visibility. So as in all things, be careful what you ask for. In some use cases you may want to see pending values and in others you may want to see only approved values. There are use cases, we have one in workflow processing for a list where we want to see both. In this case we use two identities to access the same list item and so can compare the pending and approved items.
Sharepoint 2013 REST API: The C# Connection: Part 4 Document Libraries, Folders And Files
Sharepoint 2013 REST API: The C# Connection: Part 5 REST API More on Folders and Other Odds & Ends
Coming up: Document processing!
The Google Barge In Portland Maine. Don’t believe the cover story. It’s a 3D printer which can only produce other 3D printer barges!